Merge branch 'main' into cleanup/cli-protocol-vocab

Delete dead v1 config knobs and the broken pnpm auth script

repo-tokens/badge.svg

@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="208k tokens, 104% of context window">
-  <title>208k tokens, 104% of context window</title>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="90" height="20" role="img" aria-label="207k tokens, 104% of context window">
+  <title>207k tokens, 104% of context window</title>
   <linearGradient id="s" x2="0" y2="100%">
     <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
     <stop offset="1" stop-opacity=".1"/>
@@ -15,8 +15,8 @@
       <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
         <text aria-hidden="true" x="26" y="15" fill="#010101" fill-opacity=".3">tokens</text>
         <text x="26" y="14">tokens</text>
-        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">208k</text>
-        <text x="71" y="14">208k</text>
+        <text aria-hidden="true" x="71" y="15" fill="#010101" fill-opacity=".3">207k</text>
+        <text x="71" y="14">207k</text>
       </g>
     </g>
   </a>

src/cli/commands/help.ts

@@ -27,7 +27,7 @@ register({
     if (cliScope === 'group') {
       resources = resources.filter((r) => GROUP_SCOPE_RESOURCES.has(r.plural));
     }
-    const commands = listCommands().filter((c) => c.access !== 'hidden' && !c.resource);
+    const commands = listCommands().filter((c) => !c.resource);
 
     const lines: string[] = [];
 

src/cli/crud.ts

@@ -10,14 +10,13 @@ import { randomUUID } from 'crypto';
 
 import { getDb } from '../db/connection.js';
 import { register } from './registry.js';
+import type { Access } from './registry.js';
 import type { CallerContext } from './frame.js';
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export type Access = 'open' | 'approval' | 'hidden';
-
 export interface ColumnDef {
   name: string;
   type: 'string' | 'number' | 'boolean' | 'json';

src/cli/frame.ts

@@ -11,7 +11,7 @@
 export type RequestFrame = {
   /** Correlation key set by the client. */
   id: string;
-  /** Registry name, e.g. "list-groups". */
+  /** Registry name, e.g. "groups-list". */
   command: string;
   /** Command-specific. Each command's parseArgs validates. */
   args: Record<string, unknown>;
@@ -24,10 +24,8 @@ export type ResponseFrame =
 export type ErrorCode =
   | 'unknown-command'
   | 'invalid-args'
-  | 'permission-denied'
   | 'forbidden'
   | 'approval-pending'
-  | 'not-found'
   | 'handler-error'
   | 'transport-error';
 

src/cli/registry.ts

@@ -1,19 +1,28 @@
 /**
  * Command registry — single source of truth for what `ncl` can do.
  *
- * Each command file under `commands/` calls `register()` at top level,
- * and `commands/index.ts` imports them all for side effects so the
- * registry is populated before the host's CLI server accepts connections.
+ * Most commands come from resource modules under `resources/`, which call
+ * `registerResource()` (one `register()` per CRUD verb); the top-level `help`
+ * command and the per-resource help commands register directly. The barrel
+ * `commands/index.ts` imports the resource barrel for its side effects and then
+ * registers the help commands, so the registry is populated before the host's
+ * CLI server accepts connections.
  */
 import type { CallerContext } from './frame.js';
 
-export type Access = 'open' | 'approval' | 'hidden';
+export type Access = 'open' | 'approval';
 
 export type CommandDef<TArgs = unknown, TData = unknown> = {
   name: string;
   description: string;
   access: Access;
-  /** Resource this command belongs to (for help grouping). */
+  /**
+   * The group-scope whitelist key. Under `cli_scope: 'group'` the dispatcher
+   * only lets an agent run commands whose `resource` is on the whitelist
+   * (`groups`, `sessions`, `destinations`, `members`); it also drives help
+   * grouping. Omitting `resource` exempts the command from the whitelist —
+   * that's how general commands like `help` stay reachable in group scope.
+   */
   resource?: string;
   /**
    * Set on the auto-generated `list` / `get` handlers (see `registerResource`).