@north-light/crouter 0.3.163 → 0.3.165

package/dist/commands/memory/lint.js

@@ -70,7 +70,7 @@ export function lintBodyLength(fm, body, docName) {
     const sys = fm['system-prompt-visibility'];
     const file = fm['file-read-visibility'];
     const words = countBodyWords(body);
-    const remedy = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs saved at `none` visibility on both axes (the link is how they are found, so they cost nothing until followed). Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
+    const remedy = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs saved at `none` visibility on both axes (the link is how they are found, so they cost nothing until followed). Split by subject: each leaf covers a different subject a task might need on its own; never split off “further evidence”, examples, or references — a references leaf is never followed, so supporting material stays next to the point it supports or gets cut. Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
     if (sys === 'content' && words > SYSTEM_CONTENT_MAX_WORDS) {
         return `body is ${words} words but system-prompt-visibility: content inlines every word into every agent's system prompt at boot — capped at ${SYSTEM_CONTENT_MAX_WORDS} words (system-prompt preview gets ${SYSTEM_PREVIEW_MAX_WORDS}; name/none are never capped on that axis). ${remedy}`;
     }

package/dist/commands/memory/write.js

@@ -23,7 +23,7 @@ export const writeLeaf = defineLeaf({
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the READER’s payoff — the consequence they secure for the task in front of them by spending the read — never what the document says, its rule, or why it should be obeyed. The trap most authors fall into is the DISGUISED restatement: a because-clause that reads like a benefit but is just the doc’s own thesis reworded as an outcome. It still fails. The test: if you could derive the because-clause by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad (naked restatement): "because only genuine first principles belong in taste memory." Bad (restatement in benefit’s clothing): "because keeping the test loop fast and free of speculative tests protects the development pace" — that is the doc’s rule in outcome costume, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." The stranger test: someone mid-task who has NOT read the doc must be able to decide from this one line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
             'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name — the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc’s resolvable links alongside its body. There is no alias or label form.\n\n' +
-            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]` as further reading. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. This is the same layering the visibility rungs apply to boot cost, applied to the body itself. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
+            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. This is the same layering the visibility rungs apply to boot cost, applied to the body itself. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
             'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body that would make the existing document harder to route or use. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Run `crtr memory lint` — the frontmatter validator — after authoring.\n\n' +
             '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. The bar: if the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into, so a merely-plausible-sounding reason is not worth recording. It is maintainer-facing only and NEVER ships in a delivered surface (boot render, on-read injection, `memory read` content) — it lives in frontmatter, visible only via `memory read --frontmatter`. Omit it when you have no such gap to record; omitting the flag on an update always preserves whatever rationale already exists.',
         params: [

package/dist/commands/node.js

@@ -247,7 +247,7 @@ const nodeCreationEngine = defineLeaf({
             'Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.',
             'A managed child creates an active parent subscription; --root creates an independent node with spawned_by provenance and no parent subscription.',
             '--worktree creates a managed worktree. --output-schema writes nodes/<id>/output-schema.json. --no-kickoff starts an idle root without a first model turn.',
-            'An in-tmux root opens a viewer; a managed child opens beside a live spawner viewer when one exists.',
+            'An in-tmux root opens a viewer. When auto_open_child_viewers is true, a managed child opens beside a live spawner viewer; false leaves it running in the background.',
         ],
     },
     run: async (input) => {
@@ -384,7 +384,7 @@ const nodeNew = defineLeaf({
             'Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.',
             'A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.',
             '--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch. --output-schema writes nodes/<id>/output-schema.json. --no-kickoff starts an idle root without a first model turn.',
-            'An in-tmux root opens a viewer in the current tmux session; a managed child opens beside a live spawner viewer when one exists.'
+            'An in-tmux root opens a viewer in the current tmux session. When auto_open_child_viewers is true, a managed child opens beside a live spawner viewer; false leaves it running in the background.'
         ],
     },
     run: async (input, context) => {

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

@@ -2,7 +2,7 @@ import { defineLeaf } from '../../core/command.js';
 import { notFound } from '../../core/errors.js';
 import { paginate } from '../../core/pagination.js';
 import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
-import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { listPluginMemoryDocs } from '../../core/memory-resolver.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
 import { SUBTREE_NAMES } from '../../build-root.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
@@ -20,7 +20,7 @@ export const pluginList = defineLeaf({
             { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, scope, version?, enabled, source_marketplace?, path}. Sorted by scope then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, scope, version?, enabled, transport, source_marketplace?, path}. transport is exec or http for command plugins, null for docs-only plugins. Sorted by scope then name ascending.' },
             { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
             { name: 'total', type: 'integer | null', required: true, constraint: 'Exact when cheap; null otherwise.' },
         ],
@@ -65,6 +65,7 @@ export const pluginList = defineLeaf({
                 scope: p.scope,
                 version: p.version,
                 enabled: p.enabled,
+                transport: p.manifest.transport?.kind ?? null,
                 source_marketplace: p.sourceMarketplace,
                 path: p.root,
             })),
@@ -91,10 +92,10 @@ export const pluginShow = defineLeaf({
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
-            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, executable: string | null (null when path/exec-bit validation failed), mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically — the plugin binary is never executed.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only. Command manifests are validated statically; the plugin executable is never run.'],
+        effects: ['None. Read-only. Command manifests are validated statically; commands are never executed.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -115,8 +116,7 @@ export const pluginShow = defineLeaf({
         if (found === null) {
             throw notFound(`plugin not found: ${name}`);
         }
-        const prefix = `${found.name}/`;
-        const docs = listAllMemoryDocs().filter((d) => d.name.startsWith(prefix));
+        const docs = listPluginMemoryDocs(found, found.scope);
         let commands;
         if (typeof found.manifest.commands === 'string' && found.manifest.commands.length > 0) {
             const reserved = new Set(SUBTREE_NAMES);
@@ -129,7 +129,6 @@ export const pluginShow = defineLeaf({
                 validatePluginCommands(found, reserved);
             commands = {
                 manifestPath: v.manifestPath,
-                executable: v.executable ?? null,
                 mounts: v.contributions.map((c) => c.node.name),
                 issues: v.issues,
             };

package/dist/commands/pkg/plugin-manage.d.ts

@@ -1,4 +1,4 @@
-import type { Scope } from '../../types.js';
+import { type Scope } from '../../types.js';
 interface MarketplaceRef {
     marketplace: string;
     plugin: string;

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

@@ -1,15 +1,19 @@
 import { join, resolve, isAbsolute } from 'node:path';
 import { renameSync } from 'node:fs';
 import { defineLeaf } from '../../core/command.js';
-import { notFound, usage, general } from '../../core/errors.js';
+import { CrtrError, notFound, usage, general, network } from '../../core/errors.js';
 import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
 import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
 import { updateConfig, updateState, ensureScopeInitialized } from '../../core/config.js';
-import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink } from '../../core/fs-utils.js';
+import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, atomicWriteJson } from '../../core/fs-utils.js';
 import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
-import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { pluginManifestPath, readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { normalizeEndpoint, validateEndpoint, validateHttpPluginTransport } from '../../core/command-plugins/endpoint.js';
+import { resolveHttpPluginManifestStore, writeHttpPluginManifest } from '../../core/command-plugins/store.js';
+import { fetchHttpPluginManifest, refreshHttpPlugin } from '../../core/command-plugins/transport/http-fetch.js';
 import { SUBTREE_NAMES } from '../../build-root.js';
+import { ExitCode } from '../../types.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
@@ -27,6 +31,68 @@ function commandReport(name, scope) {
         validatePluginCommands(plugin, reserved);
     return { mounts: v.contributions.map((c) => c.node.name), issues: v.issues };
 }
+const PLUGIN_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function unsafeHttpManifestPath(name, commands) {
+    throw new CrtrError('command_path_unsafe', `HTTP plugin "${name}" commands pointer escapes the plugin root or is not a regular file`, ExitCode.USAGE, { received: commands, field: 'commands', next: 'Fix plugin.json.commands.' });
+}
+function validateHttpInstall(name, endpoint, authEnv) {
+    if (typeof name !== 'string' || !PLUGIN_NAME_RE.test(name)) {
+        throw usage('invalid --name: expected a lowercase kebab-case plugin handle');
+    }
+    const endpointValidation = validateEndpoint(endpoint);
+    if (!endpointValidation.isValid) {
+        throw usage(`invalid --endpoint: ${endpointValidation.errors.join('; ')}`);
+    }
+    const normalizedEndpoint = normalizeEndpoint(endpoint);
+    const transportValidation = validateHttpPluginTransport({
+        kind: 'http',
+        endpoint: normalizedEndpoint,
+        ...(authEnv !== undefined ? { authEnv } : {}),
+    });
+    if (transportValidation.transport === undefined) {
+        throw usage(`invalid HTTP plugin transport: ${transportValidation.errors.join('; ')}`);
+    }
+    return transportValidation.transport;
+}
+async function installHttpPlugin(name, endpoint, authEnv, scope) {
+    const transport = validateHttpInstall(name, endpoint, authEnv);
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    const root = join(scopeRootPath, 'plugins', name);
+    if (pathExists(root) && readPluginManifest(root)?.transport?.kind !== 'http') {
+        throw general(`plugin "${name}" already exists at ${root} and is not an HTTP-transport plugin`);
+    }
+    if (pathExists(root) && resolveHttpPluginManifestStore({ root, commands: 'commands.json' }) === null) {
+        unsafeHttpManifestPath(name, 'commands.json');
+    }
+    const fetched = await fetchHttpPluginManifest({
+        name,
+        endpoint: transport.endpoint,
+        ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}),
+    });
+    if (fetched.status !== 200) {
+        const message = `HTTP plugin install failed for "${name}": ${fetched.message}`;
+        if (fetched.status === 'auth_env_missing')
+            throw usage(message);
+        if (fetched.status === 'cli_unreachable')
+            throw network(message);
+        throw general(message);
+    }
+    ensureScopeInitialized(scope, scopeRootPath);
+    atomicWriteJson(pluginManifestPath(root), {
+        name,
+        commands: 'commands.json',
+        transport,
+    });
+    const store = resolveHttpPluginManifestStore({ root, commands: 'commands.json' });
+    if (store === null)
+        unsafeHttpManifestPath(name, 'commands.json');
+    writeHttpPluginManifest(store, fetched.raw);
+    updateConfig(scope, (cfg) => {
+        cfg.plugins[name] = { enabled: true };
+    });
+    const commands = commandReport(name, scope);
+    return { name, scope, path: root, transport: 'http', ...(commands !== undefined ? { commands } : {}) };
+}
 function classifyInstallRef(raw) {
     if (raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/')) {
         return { kind: 'local', value: raw };
@@ -202,7 +268,23 @@ export function installFromMarketplace(ref, scope) {
     });
     return { name: ref.plugin, scope, path: destPluginDir };
 }
-function updateOnePlugin(plugin, marketplaceCache, opts) {
+async function updateOnePlugin(plugin, marketplaceCache, opts) {
+    if (plugin.manifest.transport?.kind === 'http') {
+        const commandsPath = plugin.manifest.commands;
+        if (typeof commandsPath !== 'string' || commandsPath.length === 0) {
+            throw usage(`HTTP plugin "${plugin.name}" has no commands path in plugin.json; fix the manifest before updating.`);
+        }
+        const store = resolveHttpPluginManifestStore({ root: plugin.root, commands: commandsPath });
+        if (store === null)
+            unsafeHttpManifestPath(plugin.name, commandsPath);
+        await refreshHttpPlugin({
+            name: plugin.name,
+            endpoint: plugin.manifest.transport.endpoint,
+            ...(plugin.manifest.transport.authEnv !== undefined ? { authEnv: plugin.manifest.transport.authEnv } : {}),
+        }, store);
+        const commands = commandReport(plugin.name, plugin.scope);
+        return { name: plugin.name, transport: 'http', updated: true, ...(commands !== undefined ? { commands } : {}) };
+    }
     let contentUpdate = { updated: false, sha: currentSha(plugin.root) ?? '' };
     let marketplaceVersion;
     if (plugin.sourceMarketplace !== undefined) {
@@ -227,6 +309,7 @@ function updateOnePlugin(plugin, marketplaceCache, opts) {
     const commands = commandReport(plugin.name, plugin.scope);
     return {
         name: plugin.name,
+        ...(plugin.manifest.transport?.kind === 'exec' ? { transport: 'exec' } : {}),
         updated: contentUpdate.updated,
         sha: contentUpdate.sha,
         ...(commands !== undefined ? { commands } : {}),
@@ -234,39 +317,66 @@ function updateOnePlugin(plugin, marketplaceCache, opts) {
 }
 export const pluginInstall = defineLeaf({
     name: 'install',
-    description: 'install from marketplace ref, git URL, or local path',
-    whenToUse: 'installing one plugin into a scope when you have an explicit ref: marketplace/plugin, a git URL, or a local path starting ./, ../, or /',
+    description: 'install from a ref or HTTP endpoint',
+    whenToUse: 'installing one plugin from a marketplace ref, git URL, local path, or an HTTP command-manifest endpoint',
     help: {
         name: 'pkg plugin install',
-        summary: 'install a plugin from marketplace/plugin, git URL, or local path',
+        summary: 'install a plugin from a ref or HTTP endpoint',
         params: [
-            { kind: 'positional', name: 'install-ref', type: 'string', required: true, constraint: 'Plugin install ref. Accepted forms: marketplace/plugin; git URL starting https://, ssh://, git@, file://, or ending .git; local path starting ./, ../, or /.' },
+            { kind: 'positional', name: 'install-ref', type: 'string', required: false, constraint: 'Plugin install ref. Provide exactly one of INSTALL-REF or --endpoint. Accepted ref forms: marketplace/plugin; git URL starting https://, ssh://, git@, file://, or ending .git; local path starting ./, ../, or /.' },
+            { kind: 'flag', name: 'endpoint', type: 'string', required: false, constraint: 'HTTP plugin endpoint. Provide exactly one of --endpoint or INSTALL-REF. Must be an absolute https: URL; http: is permitted only for localhost, 127.0.0.1, [::1], ::1, or host.docker.internal. Credentials and fragments are rejected.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Required with --endpoint and rejected without it. Lowercase kebab-case plugin handle.' },
+            { kind: 'flag', name: 'auth-env', type: 'string', required: false, constraint: 'Optional environment variable holding the HTTP bearer token. Accepted only with --endpoint; its value is never stored.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
-            { kind: 'flag', name: 'ref', type: 'string', required: false, constraint: 'Git ref (branch/tag) for git URL installs. Ignored for marketplace and local path refs.' },
+            { kind: 'flag', name: 'ref', type: 'string', required: false, constraint: 'Git ref (branch/tag) for git URL installs. Rejected with --endpoint; ignored for marketplace and local path refs.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Plugin name as installed.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the plugin was installed into.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the installed plugin directory.' },
-            { 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; the plugin binary is never executed.' },
+            { name: 'transport', type: 'string', required: false, constraint: 'exec or http when the plugin declares commands. Always http for an --endpoint install.' },
+            { 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.' },
         ],
         outputKind: 'object',
         effects: [
-            'Clones, links, or copies the plugin into the scope plugins directory. Registers the plugin in config.json with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
-            'If the plugin declares a command manifest, its commands go live on the next crtr invocation. A command leaf runs the plugin\'s own executable as trusted local code with your authority — only when you explicitly invoke that leaf, never on install, help, or discovery.',
+            '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 validates inputs, fetches the command manifest before writing, then writes plugin.json and commands.json and enables the plugin. Reinstalling the same HTTP plugin name replaces its stored manifest and metadata; a fetch failure writes nothing.',
+            '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.',
         ],
     },
     run: async (input) => {
         const rawRef = input['installRef'];
+        const endpoint = input['endpoint'];
+        const name = input['name'];
+        const authEnv = input['authEnv'];
         const scopeInput = input['scope'];
         const gitRef = input['ref'];
         const scope = resolveInstallScope(scopeInput);
+        if ((rawRef === undefined) === (endpoint === undefined)) {
+            throw usage('provide exactly one of INSTALL-REF or --endpoint');
+        }
+        if (endpoint !== undefined) {
+            if (name === undefined)
+                throw usage('--name is required with --endpoint');
+            if (gitRef !== undefined)
+                throw usage('--ref is only valid with a git INSTALL-REF, not --endpoint');
+            return installHttpPlugin(name, endpoint, authEnv, scope);
+        }
+        if (name !== undefined)
+            throw usage('--name is only valid with --endpoint');
+        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 plugin = findPluginByName(installed.name, installed.scope);
         const commands = commandReport(installed.name, installed.scope);
-        return commands !== undefined ? { ...installed, commands } : installed;
+        return {
+            ...installed,
+            ...(plugin?.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
+            ...(commands !== undefined ? { commands } : {}),
+        };
     },
 });
 export const pluginRemove = defineLeaf({
@@ -368,18 +478,18 @@ export const pluginDisable = defineLeaf({
 export const pluginUpdate = defineLeaf({
     name: 'update',
     description: 'update installed plugin content',
-    whenToUse: 'pulling source updates for one named plugin, or all installed plugins when no name is given; marketplace-sourced plugins refresh their source marketplace before version/content resolution',
+    whenToUse: 'refreshing one named plugin or all installed plugins: HTTP plugins re-fetch their command manifest, while local plugins retain their git update behavior',
     help: {
         name: 'pkg plugin update',
-        summary: 'update one or all installed plugins from their recorded source',
+        summary: 'refresh one or all installed plugins',
         params: [
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all installed plugins.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, updated, sha, commands?}. commands is present only for plugins declaring a command manifest: {mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})} — validated statically, never executing the plugin binary.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, commands?}. HTTP plugins report transport=http and replace commands.json after an authenticated refetch; sha is present for git updates. commands is present only for plugins declaring a command manifest: {mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})} — validated statically, never executing commands.' },
         ],
         outputKind: 'object',
-        effects: ['Runs git pull in plugin or marketplace directories when they are git checkouts. Updates plugin version and last_updated state.'],
+        effects: ['HTTP plugins unconditionally re-fetch and replace commands.json; a fetch failure exits nonzero and preserves prior bytes. Other plugins retain their git pull, version, and last_updated behavior.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -389,10 +499,12 @@ export const pluginUpdate = defineLeaf({
             if (found === null) {
                 throw notFound(`plugin not found: ${name}`);
             }
-            return { updated: [updateOnePlugin(found, marketplaceCache, { strict: true })] };
+            return { updated: [await updateOnePlugin(found, marketplaceCache, { strict: true })] };
         }
         const targets = listAllPlugins().filter((p) => p.scope !== 'builtin');
-        const results = targets.map((plugin) => updateOnePlugin(plugin, marketplaceCache, { strict: false }));
+        const results = [];
+        for (const plugin of targets)
+            results.push(await updateOnePlugin(plugin, marketplaceCache, { strict: false }));
         return { updated: results };
     },
 });

package/dist/commands/pkg/plugin.js

@@ -4,11 +4,11 @@ import { pluginList, pluginShow } from './plugin-inspect.js';
 export const pluginBranch = defineBranch({
     name: 'plugin',
     description: 'install and manage plugins',
-    whenToUse: 'working with individual plugins: install one from a marketplace/plugin ref, git URL, or local path; remove, enable, disable, update, list, or show installed plugins. Use `pkg market` only for marketplace source registration, refresh, and browsing.',
+    whenToUse: 'working with individual plugins: install, remove, enable, disable, update, list, or inspect them. Use `pkg market` only for marketplace source registration, refresh, and browsing.',
     help: {
         name: 'pkg plugin',
         summary: 'plugin lifecycle and inspection',
-        model: 'Plugins are git repos or local directories containing a .crouter-plugin/plugin.json manifest and a memory/ directory. Install refs are explicit: marketplace/plugin, git URL, or local path.',
+        model: 'A plugin may contribute memory docs and commands. Command plugins declare one transport in plugin.json: exec runs a local executable; http calls a remote endpoint. Install accepts either a source ref or an HTTP endpoint.',
     },
     children: [pluginInstall, pluginRemove, pluginEnable, pluginDisable, pluginUpdate, pluginList, pluginShow],
 });

package/dist/commands/pkg.js

@@ -1,24 +1,19 @@
-// `crtr pkg` subtree: plugin lifecycle, marketplace source management, and
-// configured-CLI lifecycle.
-// Sub-branches: plugin {install,remove,enable,disable,update,list,show}
-//               market {add,remove,update,list,browse}
-//               cli    {register,remove,list,show,refresh}
+// `crtr pkg` subtree: plugin lifecycle and marketplace source management.
 import { defineBranch } from '../core/command.js';
 import { pluginBranch } from './pkg/plugin.js';
 import { marketBranch } from './pkg/market.js';
-import { cliBranch } from './pkg/cli.js';
 export function registerPkg() {
     return defineBranch({
         name: 'pkg',
         rootEntry: {
-            concept: 'plugins, marketplaces, and configured CLIs that extend crtr',
-            desc: 'manage plugins, marketplace sources, and configured CLIs',
-            useWhen: 'installing or browsing memory-doc collections, or registering a configured CLI (a remote command surface run as declarative HTTP)',
+            concept: 'plugins and marketplaces that extend crtr',
+            desc: 'manage plugins and marketplace sources',
+            useWhen: 'installing or browsing plugins and marketplace sources; plugin commands may use local executable or remote HTTP transport',
         },
         help: {
             name: 'pkg',
-            summary: 'manage plugins, marketplace sources, and configured CLIs',
+            summary: 'manage plugins and marketplace sources',
         },
-        children: [pluginBranch, marketBranch, cliBranch],
+        children: [pluginBranch, marketBranch],
     });
 }

package/dist/commands/profile/env.js

@@ -9,7 +9,7 @@
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { loadProfileManifest } from '../../core/profiles/manifest.js';
-import { validateEnvVarName } from '../../core/configured-clis/registration.js';
+import { validateEnvVarName } from '../../core/env-name.js';
 import { listProfileEnvNames, setProfileEnvVar, removeProfileEnvVar } from '../../core/profiles/env-store.js';
 /** Strips exactly one trailing line ending (`\r\n` or `\n`) — the one
  *  documented byte the piped-value contract trims — and leaves every other
@@ -38,7 +38,7 @@ function requireValidName(name) {
 const setLeaf = defineLeaf({
     name: 'set',
     description: 'store one env var for a profile, value piped on stdin',
-    whenToUse: 'a profile needs a credential or config value injected directly into every broker launched under it \u2014 e.g. a configured CLI\u2019s `auth-env` token. Setting it here crosses the broker spawn boundary with no separate `spawnEnv.allow` entry required; re-running with the same name overwrites the value.',
+    whenToUse: 'a profile needs a credential or config value injected directly into every broker launched under it \u2014 e.g. a HTTP-transport plugin\u2019s `auth-env` token. Setting it here crosses the broker spawn boundary with no separate `spawnEnv.allow` entry required; re-running with the same name overwrites the value.',
     help: {
         name: 'profile env set',
         summary: 'write (or overwrite) one env var in a profile\u2019s 0600 env store',
@@ -184,7 +184,7 @@ const removeLeaf = defineLeaf({
 export const envBranch = defineBranch({
     name: 'env',
     description: 'manage a profile-scoped store of env vars injected into its brokers',
-    whenToUse: 'a profile needs a credential or config value available directly to every broker (and thus every node) launched under it \u2014 e.g. a configured CLI\u2019s `auth-env` token \u2014 without exporting it into the daemon\u2019s own ambient shell or granting a `spawnEnv.allow` passthrough.',
+    whenToUse: 'a profile needs a credential or config value available directly to every broker (and thus every node) launched under it \u2014 e.g. a HTTP-transport plugin\u2019s `auth-env` token \u2014 without exporting it into the daemon\u2019s own ambient shell or granting a `spawnEnv.allow` passthrough.',
     help: {
         name: 'profile env',
         summary: 'a profile\u2019s own 0600 store of env vars, injected directly into every broker launched under it',

package/dist/commands/sys/config.js

@@ -3,22 +3,12 @@ import { readConfig, updateConfig, persistModelLadders, configPath as coreConfig
 import { usage, notFound } from '../../core/errors.js';
 import { scopeRoot, requireScopeRoot, listScopes } from '../../core/scope.js';
 import { resolveScope } from './shared.js';
-import { CONDENSED_HISTORY_MODES } from '../../types.js';
+import { SCOPE_CONFIG_KEYS, USER_SETTINGS, findUserSetting } from '../../core/user-settings.js';
 // ---------------------------------------------------------------------------
 // Config helpers (ported from commands/config.ts)
 // ---------------------------------------------------------------------------
-const TOP_LEVEL_KEYS = new Set([
-    'auto_update',
-    'marketplaces',
-    'plugins',
-    'max_panes_per_window',
-    'brokerThresholds',
-    'completion_bell',
-    'live_cycles',
-    'condensed_history',
-    'fold_finished_tools',
-    'modelLadders',
-]);
+const CONFIG_TOP_LEVEL_HELP = SCOPE_CONFIG_KEYS.join(', ');
+const SCALAR_SETTING_HELP = USER_SETTINGS.map((setting) => `${setting.key} (${setting.valueConstraint})`).join(', ');
 const MODEL_PROVIDERS = new Set(['anthropic', 'openai']);
 const MODEL_STRENGTHS = new Set(['ultra', 'strong', 'medium', 'light']);
 function isModelProvider(value) {
@@ -51,6 +41,11 @@ function assertUserScopeBrokerThresholds(key, scope) {
         throw usage('brokerThresholds are available only in user scope');
     }
 }
+function assertUserSettingScope(key, scope) {
+    if (findUserSetting(key) !== undefined && scope !== 'user') {
+        throw usage(`${key} is available only in user scope`);
+    }
+}
 /** Validate a `modelLadders.*` key/value into an explicit sparse patch, or
  *  return null when the key is not a ladder key. Ladder sets do NOT go through
  *  `setNestedValue`/`updateConfig`: that path persists only what differs from
@@ -91,29 +86,11 @@ function setNestedValue(cfg, key, rawValue, value) {
     if (topKey === 'modelLadders') {
         throw usage('modelLadders keys are written through persistModelLadders, not this path');
     }
-    if (!TOP_LEVEL_KEYS.has(topKey)) {
-        throw usage(`unknown config key: ${topKey} (expected: ${[...TOP_LEVEL_KEYS].join('|')})`);
-    }
-    if (key === 'auto_update.content') {
-        if (value !== 'notify' && value !== 'apply' && value !== false) {
-            throw usage(`auto_update.content must be 'notify', 'apply', or false`);
-        }
-        cfg.auto_update.content = value;
-        return;
-    }
-    if (key === 'auto_update.crtr') {
-        const coerced = value === true ? 'notify' : value;
-        if (coerced !== 'notify' && coerced !== 'apply' && coerced !== false) {
-            throw usage(`auto_update.crtr must be 'notify', 'apply', or false`);
-        }
-        cfg.auto_update.crtr = coerced;
-        return;
-    }
-    if (key === 'max_panes_per_window') {
-        if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
-            throw usage(`max_panes_per_window must be an integer >= 1`);
-        }
-        cfg.max_panes_per_window = Math.floor(value);
+    const setting = findUserSetting(key);
+    if (setting !== undefined) {
+        const error = setting.setFromString(cfg, rawValue);
+        if (error !== null)
+            throw usage(error);
         return;
     }
     if (topKey === 'brokerThresholds') {
@@ -133,43 +110,6 @@ function setNestedValue(cfg, key, rawValue, value) {
         cfg.brokerThresholds[parts[1]] = threshold;
         return;
     }
-    if (key === 'completion_bell') {
-        if (typeof value !== 'boolean') {
-            throw usage(`completion_bell must be true or false`);
-        }
-        cfg.completion_bell = value;
-        return;
-    }
-    if (key === 'live_cycles') {
-        if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
-            throw usage(`live_cycles must be an integer >= 1`);
-        }
-        cfg.live_cycles = Math.floor(value);
-        return;
-    }
-    if (key === 'condensed_history') {
-        if (!CONDENSED_HISTORY_MODES.includes(rawValue)) {
-            throw usage(`condensed_history must be one of: ${CONDENSED_HISTORY_MODES.join('|')}`);
-        }
-        cfg.condensed_history = rawValue;
-        return;
-    }
-    if (key === 'fold_finished_tools') {
-        if (typeof value !== 'boolean') {
-            throw usage(`fold_finished_tools must be true or false`);
-        }
-        cfg.fold_finished_tools = value;
-        return;
-    }
-    if (parts.length === 1) {
-        cfg[topKey] = value;
-        return;
-    }
-    if (parts.length === 2 && topKey === 'auto_update') {
-        const subKey = parts[1];
-        cfg.auto_update[subKey] = value;
-        return;
-    }
     throw usage(`unsupported key path for set: ${key}`);
 }
 // ---------------------------------------------------------------------------
@@ -183,7 +123,7 @@ const configGet = defineLeaf({
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, brokerThresholds (user only; warning and automaticReviveCap), completion_bell, live_cycles, condensed_history, fold_finished_tools, modelLadders, or the whole keybindings object. Keybindings are edited only through sys setup.' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. Top-level keys: ${CONFIG_TOP_LEVEL_HELP}. brokerThresholds is user-only; keybindings is readable only as the whole user-scope object and editable only through sys setup.` },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
@@ -217,9 +157,9 @@ const configSet = defineLeaf({
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, brokerThresholds.warning, brokerThresholds.automaticReviveCap (user scope; positive integers), completion_bell, live_cycles (integer >= 1 — trailing cycles the attach viewer renders at full fidelity; older cycles condense to prose), condensed_history (none|user|agent|both — which messages of a condensed cycle still render; none keeps only the cycle dividers), fold_finished_tools (true|false — fold every settled tool call in the attach viewer to its single call line), modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys setup.' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys setup.` },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. Stored as-is if quoted; coerced to number or boolean when unambiguous.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user. Project scope is supported only for modelLadders.' },
         ],
         output: [
             { name: 'key', type: 'string', required: true, constraint: 'Echo of input key.' },
@@ -234,6 +174,7 @@ const configSet = defineLeaf({
         const rawValue = input['value'];
         const scope = resolveScope(input['scope']);
         assertUserScopeBrokerThresholds(key, scope);
+        assertUserSettingScope(key, scope);
         // Flags are stringly-typed; coerce to number or boolean when unambiguous
         const parsed = parseConfigValue(rawValue);
         // Ladder rungs record explicit intent (even when the value equals today's