@north-light/api 0.3.579 → 0.3.587

package/dist/commands/profile/kind.js

@@ -0,0 +1,27 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient } from '../api-client.js';
+import { kindsStateBlock, resolveProfileViaDaemon } from './daemon-profiles.js';
+export const kindLeaf = defineLeaf({
+    name: 'kind',
+    description: "set a profile's default node kind",
+    whenToUse: 'nodes created under a profile without `--kind` should use a persona other than `general`.',
+    help: {
+        name: 'profile kind',
+        summary: "set a profile's manifest `default_kind` for creates that omit --kind",
+        params: [
+            { kind: 'positional', name: 'profile', required: true, constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.' },
+            { kind: 'positional', name: 'kind', required: true, constraint: 'Installed persona kind to use by default. The live <kinds> list below is the accepted value set.' },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+        ],
+        outputKind: 'object',
+        effects: ["Sets the profile manifest's `default_kind`. Future node creates under the profile that omit --kind resolve to it server-side."],
+    },
+    helpState: { leaf: kindsStateBlock },
+    run: async (input) => {
+        const { id } = await resolveProfileViaDaemon(input['profile']);
+        await cliClient().updateProfile(id, { default_kind: input['kind'] });
+        return { profile_id: id };
+    },
+});

package/dist/commands/profile/list.d.ts

@@ -0,0 +1 @@
+export declare const listLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/list.js

@@ -0,0 +1,45 @@
+import { defineLeaf } from '../../core/command.js';
+import { emitLine } from '../../core/io.js';
+import { cliClient } from '../api-client.js';
+export const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory every profile visible to you and its project relationships',
+    whenToUse: 'browse every profile that exists — one line each with its id, name, explicit project relationships, owning app, 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 the daemon shows the caller (its own app\'s, plus any another app shared) as JSONL, 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 `{path}` project relationships on the manifest.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'Explicit `{path}` relationships in manifest order. `path` defines profile purview; the repos enclosing each path are in the view of every node of the profile.' },
+            { name: 'app', type: 'string', required: true, constraint: 'The app that owns this 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', required: true, constraint: 'Default node kind for creates that omit --kind; `general` when none is stored.' },
+            { name: 'environment_id', type: 'string', required: true, constraint: 'Object id of the environment the profile runs in; the machine environment when none is stored.' },
+            { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
+        ],
+        outputKind: 'jsonl',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => {
+        const all = (await cliClient().listProfiles()).sort((a, b) => {
+            const nc = a.name.localeCompare(b.name);
+            return nc !== 0 ? nc : a.id.localeCompare(b.id);
+        });
+        for (const p of all) {
+            emitLine({
+                profile_id: p.id,
+                name: p.name,
+                projects_count: p.projects.length,
+                projects: p.projects,
+                app: p.app,
+                paused_at: p.paused_at,
+                default_kind: p.default_kind,
+                environment_id: p.environment_id,
+                last_used_at: p.last_used_at,
+            });
+        }
+        emitLine({ follow_up: 'Show one in full with `crtr profile show <profile>`.' });
+    },
+});

package/dist/commands/profile/meta.d.ts

@@ -0,0 +1,4 @@
+/** Fold `KEY=VALUE` flag repetitions into one map. Key-shape validation stays
+ *  with the manifest store (`assertProfileMetadata`); this only splits. */
+export declare function resolveMetaPairs(raw: unknown, field: string): Record<string, string>;
+export declare const metaLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/meta.js

@@ -0,0 +1,65 @@
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient } from '../api-client.js';
+import { resolveProfileViaDaemon } from './daemon-profiles.js';
+/** Fold `KEY=VALUE` flag repetitions into one map. Key-shape validation stays
+ *  with the manifest store (`assertProfileMetadata`); this only splits. */
+export function resolveMetaPairs(raw, field) {
+    const pairs = Array.isArray(raw) ? raw.map(String) : typeof raw === 'string' && raw !== '' ? [raw] : [];
+    // Null prototype: on a plain object a `__proto__` key would silently
+    // vanish here instead of reaching the store's key-shape rejection.
+    const out = Object.create(null);
+    for (const pair of pairs) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0) {
+            throw new InputError({
+                error: 'bad_meta',
+                message: `"${pair}" is not KEY=VALUE`,
+                field,
+                next: `Pass --${field} KEY=VALUE (repeat the flag per entry).`,
+            });
+        }
+        out[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return out;
+}
+function resolveNames(raw) {
+    return Array.isArray(raw) ? raw.map(String) : typeof raw === 'string' && raw !== '' ? [raw] : [];
+}
+export const metaLeaf = defineLeaf({
+    name: 'meta',
+    description: "set or remove entries in a profile's metadata map",
+    whenToUse: 'a profile should carry (or stop carrying) identity facts — a display name, role, description — that every node launched under it reads from its env as `CRTR_PROFILE_META_<KEY>`. For secrets, use `profile env` instead: metadata is readable back from every projection.',
+    help: {
+        name: 'profile meta',
+        summary: "merge entries into (or drop entries from) a profile manifest's `metadata` map",
+        params: [
+            { kind: 'positional', name: 'profile', required: true, constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.' },
+            { kind: 'flag', name: 'set', type: 'string', required: false, repeatable: true, constraint: 'KEY=VALUE to merge over the stored map (repeat per entry). KEY starts with a letter or digit, followed by letters, digits, `_`, or `-`; an existing key is overwritten.' },
+            { kind: 'flag', name: 'unset', type: 'string', required: false, repeatable: true, constraint: 'KEY to remove (repeat per entry). Removing an absent key is a no-op.' },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'metadata', type: 'object', required: true, constraint: 'The full resulting metadata map.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            "Rewrites the profile manifest's `metadata` map (omitted entirely when the result is empty).",
+            'Every broker launched under this profile from now on sees each entry as `CRTR_PROFILE_META_<KEY>` (key uppercased, non-alphanumeric runs → `_`). Already-running nodes pick up changes on their next revive.',
+        ],
+    },
+    run: async (input) => {
+        const set = resolveMetaPairs(input['set'], 'set');
+        const unset = resolveNames(input['unset']);
+        if (Object.keys(set).length === 0 && unset.length === 0) {
+            throw new InputError({
+                error: 'nothing_to_do',
+                message: 'pass at least one --set KEY=VALUE or --unset KEY',
+                next: 'Repeat --set/--unset per entry.',
+            });
+        }
+        const { id } = await resolveProfileViaDaemon(input['profile']);
+        const updated = await cliClient().updateProfileMetadata(id, { set, unset });
+        return { profile_id: updated.id, metadata: updated.metadata };
+    },
+});

package/dist/commands/profile/new.d.ts

@@ -0,0 +1 @@
+export declare const newLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/new.js

@@ -0,0 +1,95 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { resolve } from 'node:path';
+import { cliClient } from '../api-client.js';
+import { resolveMetaPairs } from './meta.js';
+export const newLeaf = defineLeaf({
+    name: 'new',
+    description: 'create a new profile',
+    whenToUse: 'you are establishing a new agent identity — a stable id, a display name, and its own documents (a profile owns documents like any other owner). Pass at most one initial project directory here (the parser has no repeatable-flag support); use `profile project add` afterward for every additional one. Use `--root` (no name) to provision the canonical stable root profile — the default identity a home falls back to — idempotently, without spawning a node.',
+    help: {
+        name: 'profile new',
+        summary: "create a profile of the caller's app in the scoped store, with its own app directory",
+        params: [
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: false,
+                constraint: 'Display name for the profile. Also slugified into the stable profile id — the id never changes on later rename. Required unless `--root` is given; mutually exclusive with `--root`.',
+            },
+            {
+                kind: 'flag',
+                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`.',
+            },
+            {
+                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. Creates a purview relationship: the repos enclosing it join the view of every node of the profile, with no delivery limit (`profile project add` starts them at `preview`). Singular — add more with `crtr profile project add` after creation.",
+            },
+            {
+                kind: 'flag',
+                name: 'default-kind',
+                type: 'string',
+                required: false,
+                constraint: 'Installed persona kind for node creates under this profile that omit --kind. Defaults to general when omitted; the daemon validates it against its installed kind registry.',
+            },
+            {
+                kind: 'flag',
+                name: 'meta',
+                type: 'string',
+                required: false,
+                repeatable: true,
+                constraint: 'KEY=VALUE metadata entry (repeat per entry). KEY starts with a letter or digit, followed by letters, digits, `_`, or `-`. Each entry reaches every broker launched under the profile as `CRTR_PROFILE_META_<KEY>` env; readable back via `profile show` — not for secrets (those go to `profile env`).',
+            },
+        ],
+        output: [
+            { 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: 'profile_path', type: 'string', required: true, constraint: 'Absolute path to the profile directory, `<app space>/profiles/<id>`: its settings root. Documents the profile owns are canvas documents, read with `crtr canvas read`, not files here.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'Explicit `{path}` project relationships in manifest order. `path` defines purview and puts the repos enclosing it in the view of every node of the profile. Empty when --project was omitted.' },
+            { name: 'app', type: 'string', required: true, constraint: 'The app that owns this profile.' },
+            { name: 'default_kind', type: 'string', required: true, constraint: 'Default persona kind for node creates that omit --kind; `general` when none is stored.' },
+            { name: 'metadata', type: 'object', required: true, constraint: 'Stored metadata map; empty when --meta was omitted.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
+        ],
+        outputKind: 'object',
+        effects: ["Creates a profile row owned by the caller's app (the terminal app for a person) and its directory under that app's space. A name the caller's app already holds is refused."],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const project = input['project'];
+        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`.');
+            }
+            return newProfileOutput(await cliClient().ensureProfile('root'));
+        }
+        if (name === undefined)
+            throw usage('provide `--name <name>` to create a profile, or `--root` to provision the stable root profile.');
+        return newProfileOutput(await cliClient().createProfile({
+            name,
+            ...(project !== undefined ? { projects: [{ path: resolve(project) }] } : {}),
+            ...(defaultKind !== undefined ? { default_kind: defaultKind } : {}),
+            ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+        }));
+    },
+});
+function newProfileOutput(p) {
+    return {
+        profile_id: p.id,
+        profile_path: p.profile_path,
+        projects: p.projects,
+        app: p.app,
+        default_kind: p.default_kind,
+        metadata: p.metadata,
+        created_at: p.created_at,
+    };
+}

package/dist/commands/profile/pause.d.ts

@@ -0,0 +1,2 @@
+export declare const pauseLeaf: import("../../core/command.js").LeafDef;
+export declare const resumeLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/pause.js

@@ -0,0 +1,59 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { resolveProfileViaDaemon } from './daemon-profiles.js';
+const profileParam = {
+    kind: 'positional',
+    name: 'profile',
+    required: true,
+    constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+};
+export const pauseLeaf = defineLeaf({
+    name: 'pause',
+    description: 'make a profile inert',
+    whenToUse: 'all work under a profile must stop now while in-flight bash commands continue under their detached supervisors.',
+    help: {
+        name: 'profile pause',
+        summary: 'pause a profile so it creates and revives no nodes',
+        params: [profileParam],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'paused_at', type: 'string', required: true, constraint: 'ISO 8601 timestamp when the profile became inert.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes `paused_at`, SIGTERMs every live broker under the profile so its foreground bash hands off to its detached supervisor, and holds cron, deadline, revive, and inbox delivery until resume.'],
+    },
+    run: async (input) => {
+        const { id: profileId } = await resolveProfileViaDaemon(input['profile']);
+        try {
+            return { ...await cliClient().pauseProfile(profileId) };
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+export const resumeLeaf = defineLeaf({
+    name: 'resume',
+    description: 'make a paused profile active',
+    whenToUse: 'nodes under a paused profile may create and revive again, including queued inbox delivery.',
+    help: {
+        name: 'profile resume',
+        summary: 'resume a profile so it may create and revive nodes again',
+        params: [profileParam],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'paused_at', type: 'null', required: true, constraint: 'Always null after resume; null means active.' },
+        ],
+        outputKind: 'object',
+        effects: ['Clears `paused_at`, credits active node deadlines for the paused interval, and lets retained inbox mail, due crons, and interrupted turns resume.'],
+    },
+    run: async (input) => {
+        const { id: profileId } = await resolveProfileViaDaemon(input['profile']);
+        try {
+            return { ...await cliClient().resumeProfile(profileId) };
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});

package/dist/commands/profile/project.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const projectBranch: BranchDef;

package/dist/commands/profile/project.js

@@ -0,0 +1,134 @@
+// `crtr profile project` manages purview relationships and per-owner automatic delivery limits.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { resolve } from 'node:path';
+import { cliClient } from '../api-client.js';
+import { resolveProfileViaDaemon } from './daemon-profiles.js';
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
+const addLeaf = defineLeaf({
+    name: 'add',
+    description: "add a project to a profile's purview",
+    whenToUse: "a profile needs purview over another project directory — extend it after creation.",
+    help: {
+        name: 'profile project add',
+        summary: "add a project relationship to a profile, deduped by real path",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+            {
+                kind: 'flag',
+                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 profile keeps its position and nothing changes.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'The updated `{path}` relationships in profile order. `path` defines purview.' },
+        ],
+        outputKind: 'object',
+        effects: ["Appends a new project relationship to the profile row. Purview follows `path` for config, and every repo enclosing `path` joins the view of every node of the profile: its documents are readable, listed, and delivered at boot and workspace-open. Each such repo starts at a `preview` delivery limit unless the profile already limits that handle (change it with `profile project limit`). Running brokers discover the updated projects on their next scope read."],
+    },
+    run: async (input) => {
+        const { id } = await resolveProfileViaDaemon(input['profile']);
+        const updated = await cliClient().updateProfile(id, {
+            add_project: { path: resolve(input['dir']) },
+        });
+        return { profile_id: updated.id, projects: updated.projects };
+    },
+});
+const removeLeaf = defineLeaf({
+    name: 'remove',
+    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',
+        summary: "remove a project directory from a profile's manifest",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: "Directory to remove, matched against the stored project `path`. Does not require the directory to still exist on disk. The profile's app home does not change.",
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'The updated `{path}` relationships in profile order.' },
+        ],
+        outputKind: 'object',
+        effects: ["Removes a project relationship from the profile row. This narrows purview and drops the path's repos from the view of the profile's nodes (unless a node's cwd is inside them); delivery limits are left in place. Running brokers discover the updated projects on their next scope read."],
+    },
+    run: async (input) => {
+        const { id } = await resolveProfileViaDaemon(input['profile']);
+        const updated = await cliClient().updateProfile(id, { remove_project: resolve(input['dir']) });
+        return { profile_id: updated.id, projects: updated.projects };
+    },
+});
+const limitLeaf = defineLeaf({
+    name: 'limit',
+    description: "set how much of one owner's documents automatic delivery may disclose",
+    whenToUse: "a profile's nodes should get less of one owner's documents (a repo, `user`, an app, a plugin) at boot and workspace-open — or that limit should be lifted.",
+    help: {
+        name: 'profile project limit',
+        summary: "set a profile's automatic delivery limit for one owner handle",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+            {
+                kind: 'flag',
+                name: 'owner',
+                type: 'string',
+                required: true,
+                constraint: 'Owner the limit applies to. A bare handle (`crouter`, `user`) matches an owner of any type holding that handle. `<type>:<handle>` names one owner exactly — `repo:crouter`, `profile:work`, `app:terminal`, `person:user` — and wins over a bare key; use it when a repo and another owner share a handle. A profile\'s own documents are never capped, whichever key matches.',
+            },
+            {
+                kind: 'flag',
+                name: 'level',
+                type: 'enum',
+                choices: [...PROFILE_PROJECT_MEMORY_VALUES],
+                required: true,
+                constraint: "Maximum automatic delivery of this owner's documents at boot and workspace-open: `none`, `name`, `preview`, or `content`. `content` is no limit and removes the entry. Does not change explicit `crtr canvas read` access.",
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'delivery_limits', type: 'object', required: true, constraint: 'The profile’s limits after the change, keyed by owner handle or `<type>:<handle>`; an owner not listed is not limited.' },
+        ],
+        outputKind: 'object',
+        effects: ["Sets or removes one entry in the profile's `delivery_limits`. It caps only automatic `boot` and `workspace-open` delivery; a node's own documents and its own profile's documents are never capped. A `<type>:<handle>` key (for example `repo:crouter`) names one owner exactly and wins over a bare handle key."],
+    },
+    run: async (input) => {
+        const { id } = await resolveProfileViaDaemon(input['profile']);
+        const updated = await cliClient().updateProfile(id, {
+            set_delivery_limit: { owner: input['owner'], level: input['level'] },
+        });
+        return { profile_id: updated.id, delivery_limits: updated.delivery_limits };
+    },
+});
+export const projectBranch = defineBranch({
+    name: 'project',
+    description: "manage a profile's project purview and automatic delivery limits",
+    whenToUse: "changing a profile’s project purview after creation, or limiting how much of one owner's documents its nodes get automatically.",
+    help: {
+        name: 'profile project',
+        summary: "manage project purview and per-owner automatic delivery limits",
+        model: "Each `{path}` relationship widens purview: the profile resolves config from `path`, and every node of the profile sees the repos enclosing `path` in addition to the repos enclosing its own cwd (cwd repos first, then projects in manifest order). Rule `if: {repo}` conditions hold for any of those repos (cwd repos and project repos); `--owner repo` stays with the cwd's repos, while a node may change a project repo's documents when its file permissions allow writing that checkout. `add` appends a new real path and starts its repos at a `preview` limit; `remove` narrows purview. `limit` sets the profile's `delivery_limits` entry for one owner handle, which caps automatic boot and workspace-open delivery of that owner's documents, whether the repo is in view through the cwd or the project list; explicit reads are not capped. Purview and delivery limits are both independent of a per-cwd default pin (`crtr profile default`).",
+    },
+    children: [addLeaf, removeLeaf, limitLeaf],
+});

package/dist/commands/profile/rename.d.ts

@@ -0,0 +1 @@
+export declare const renameLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/rename.js

@@ -0,0 +1,41 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient } from '../api-client.js';
+import { resolveProfileViaDaemon } from './daemon-profiles.js';
+export const renameLeaf = defineLeaf({
+    name: 'rename',
+    description: "change a profile's name and canvas handle",
+    whenToUse: "you want the profile to appear under a new name in bearings, listings, and `profile` subject gates. The profile id (its directory) never changes.",
+    help: {
+        name: 'profile rename',
+        summary: "change a profile's name — its manifest `name` and its canvas handle (`[[name/x]]` links, `owner=` listings) — while the profile_id stays stable",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name (the CURRENT name, before this rename); a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'New display name.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id — unchanged by this leaf.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            "Changes the profile manifest's `name` field and renames the profile's canvas handle in the same daemon operation.",
+            'Refuses, before changing anything, when another live profile already holds the new handle. Links are edges to ids, so they keep resolving and render the new name.',
+            'A later profile may take the old name.',
+        ],
+    },
+    run: async (input) => {
+        const { id } = await resolveProfileViaDaemon(input['profile']);
+        await cliClient().updateProfile(id, { name: input['name'] });
+        return { profile_id: id };
+    },
+});

package/dist/commands/profile/show.d.ts

@@ -0,0 +1 @@
+export declare const showLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/show.js

@@ -0,0 +1,55 @@
+import { defineLeaf } from '../../core/command.js';
+import { resolveProfileViaDaemon } from './daemon-profiles.js';
+export const showLeaf = defineLeaf({
+    name: 'show',
+    description: "one profile's manifest in full",
+    whenToUse: "you need a profile's full project list, owning app, id, and timestamps — after `profile list` narrows to a name, to find where its nodes will run, or to inspect what a node's bearings named as its profile.",
+    help: {
+        name: 'profile show',
+        summary: "print one profile's settings and directory path",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr. A name shared by several profiles fails listing every matching id.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
+            { name: 'projects', type: 'ProfileProject[]', required: true, constraint: 'Explicit `{path}` relationships in manifest order. `path` defines profile purview; the repos enclosing each path are in the view of every node of the profile.' },
+            { name: 'app', type: 'string', required: true, constraint: 'The app that owns this 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', required: true, constraint: 'Default node kind for creates that omit --kind; `general` when none is stored.' },
+            { name: 'metadata', type: 'object', required: true, constraint: 'Stored metadata map — each entry reaches brokers launched under the profile as `CRTR_PROFILE_META_<KEY>` env. Empty when none.' },
+            { name: 'environment_id', type: 'string', required: true, constraint: 'Object id of the environment the profile runs in; the machine environment when none is stored.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
+            { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
+            { name: 'profile_path', type: 'string', required: true, constraint: 'Absolute path to the profile directory, `<app space>/profiles/<id>`: its settings root. Documents the profile owns are canvas documents, read with `crtr canvas read`, not files here.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands, including the SQL-backed raw settings surface.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const p = await resolveProfileViaDaemon(input['profile']);
+        const profileId = p.id;
+        return {
+            profile_id: profileId,
+            name: p.name,
+            projects: p.projects,
+            app: p.app,
+            paused_at: p.paused_at,
+            default_kind: p.default_kind,
+            metadata: p.metadata,
+            environment_id: p.environment_id,
+            created_at: p.created_at,
+            last_used_at: p.last_used_at,
+            profile_path: p.profile_path,
+            follow_up: p.paused_at === null
+                ? `Inspect its SQL-backed settings with \`crtr sys config get-raw --scope profile --profile ${profileId}\`; manage its purview with \`crtr profile project add ${profileId} --dir <path>\`, pause it with \`crtr profile pause ${profileId}\`, or set its default kind with \`crtr profile kind ${profileId} <kind>\`.`
+                : `Inspect its SQL-backed settings with \`crtr sys config get-raw --scope profile --profile ${profileId}\`; manage its purview with \`crtr profile project add ${profileId} --dir <path>\`, or resume it with \`crtr profile resume ${profileId}\`.`,
+        };
+    },
+});

package/dist/commands/profile.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerProfile(): BranchDef;

package/dist/commands/profile.js

@@ -0,0 +1,35 @@
+// `crtr profile` subtree — the profile store (spec §2.1/§2.5): agent
+// identities defined at the user root, each owning a manifest naming project
+// directories; the profile is also an owner of documents.
+//
+// Every manifest verb but `new`/`list` takes <profile> as an exact id, a
+// manifest name, or the closest match to one. `delete` is the one exception:
+// an irreversible verb never runs against a guessed target.
+import { defineBranch } from '../core/command.js';
+import { newLeaf } from './profile/new.js';
+import { listLeaf } from './profile/list.js';
+import { showLeaf } from './profile/show.js';
+import { renameLeaf } from './profile/rename.js';
+import { deleteLeaf } from './profile/delete.js';
+import { pauseLeaf, resumeLeaf } from './profile/pause.js';
+import { kindLeaf } from './profile/kind.js';
+import { metaLeaf } from './profile/meta.js';
+import { projectBranch } from './profile/project.js';
+import { defaultBranch } from './profile/default.js';
+import { envBranch } from './profile/env.js';
+export function registerProfile() {
+    return defineBranch({
+        name: 'profile',
+        rootEntry: {
+            concept: 'an agent identity defined at the user root — a scoped-state row naming project directories; it also owns documents',
+            desc: 'create, inspect, and manage profiles',
+            useWhen: 'creating a new agent identity, inspecting or listing existing ones, changing a profile\u2019s project purview, pinning which profile a directory defaults to at startup, or managing a profile\u2019s stored env vars. Selecting a profile for a one-off run (`--profile`) lives elsewhere.',
+        },
+        help: {
+            name: 'profile',
+            summary: 'create, inspect, and manage profiles \u2014 agent identities that own documents and have their own project purview',
+            model: 'A node\u2019s app owns its home; the profile does not select it. A node lands in the directory it was launched from when there is one: `node new --cwd`, an inherited spawner directory (notably inside a managed worktree), or the directory a root was started in. So one profile can cover many working directories — cwd selects the identity, and the launch decides where the work happens. `new` creates one from a name (+ at most one initial `--project`). `list` inventories every profile as JSONL. `show` prints one profile definition in full. `rename` changes only the profile name \u2014 the profile_id is stable across a rename. `delete --force` removes the profile after cascading through its nodes, matching schedules, originating inbox/review state, and default pins; `--detach --force` instead preserves nodes and human history while clearing the profile identity and globalizing its schedules. Both modes block while a matching node owns an open managed worktree and never touch the project directories the profile pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves repo documents + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. `meta` edits the profile\u2019s readable metadata map \u2014 identity facts each broker under the profile sees as `CRTR_PROFILE_META_<KEY>` env (secrets stay in `env`). Every manifest verb but `new`/`list` takes <profile> as an exact id, a profile name, or a close-enough name that resolves to the nearest profile (reported on stderr); a name shared by several profiles, or one equally close to several, fails listing every matching id. `delete` alone never guesses — an irreversible verb requires an exact id or name.',
+        },
+        children: [newLeaf, listLeaf, showLeaf, renameLeaf, pauseLeaf, resumeLeaf, kindLeaf, metaLeaf, deleteLeaf, projectBranch, defaultBranch, envBranch],
+    });
+}

package/dist/commands/push.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerPush(): BranchDef;