recess-cli 1.9.2 → 2.0.0

package/dist/skill-update.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { cliRequestHeaders } from "./http.js";
 import { skillDestinations } from "./setup.js";
 /**
  * Compare dotted numeric versions. Deliberately hand-rolled rather than adding a
@@ -88,7 +89,7 @@ export async function updateSkillFromServer(input) {
     let bundle;
     try {
         const response = await fetch(new URL("/auth/admin-cli/skill/", input.apiOrigin), {
-            headers: input.sessionCookie ? { cookie: input.sessionCookie } : {},
+            headers: cliRequestHeaders(input.sessionCookie ? { cookie: input.sessionCookie } : undefined, input.reason),
             signal: AbortSignal.timeout(10_000),
         });
         if (!response.ok) {

package/dist/ui/index.js

@@ -3,6 +3,7 @@ import { render } from "ink";
 import { RecessAdminApi } from "../api.js";
 import { resolveConfig } from "../config.js";
 import { CliError } from "../errors.js";
+import { RECESS_CLIENT_CLI_UI } from "../http.js";
 import { App } from "./app.js";
 /**
  * The interactive console. Kept off the JSON path on purpose: agents parse
@@ -14,7 +15,7 @@ export async function runUi() {
     if (!config.sessionCookie) {
         throw new CliError("auth_required", "No Recess CLI session found. Run `recess auth login`.");
     }
-    const api = new RecessAdminApi(config);
+    const api = new RecessAdminApi(config, undefined, RECESS_CLIENT_CLI_UI);
     const instance = render(_jsx(App, { api: api }));
     await instance.waitUntilExit();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recess-cli",
-  "version": "1.9.2",
+  "version": "2.0.0",
   "description": "Safe Recess administration and family AI tools from the command line.",
   "license": "UNLICENSED",
   "repository": {

package/skill/recess-cli/SKILL.md

@@ -11,7 +11,7 @@ Use the installed `recess` command for Recess work. This small skill is shared b
 
 ```bash
 command -v recess
-recess --json doctor
+recess --json doctor --reason "Verify CLI connectivity, identity, and scope"
 ```
 
 `doctor` reports the active API origin, authenticated user, and CLI scope. Do not assume a role from the request. Use the scope returned by the server.
@@ -20,17 +20,19 @@ Then load the guidance for the purpose of the work:
 
 ```bash
 # Parent or guardian work: kids, schedules, goals, todos, progress, memory, Rocky
-recess --json skills guardian get recess-family --all-references
+recess --json skills guardian get recess-family --all-references --reason "Load family workflow guidance"
 
 # Research, author, validate, or apply a goal or reusable goal template
-recess --json skills guardian get recess-goal-authoring --all-references
+recess --json skills guardian get recess-goal-authoring --all-references --reason "Load goal authoring guidance"
 
 # Staff-only school operations
-recess --json skills admin get recess-admin --all-references
+recess --json skills admin get recess-admin --all-references --reason "Load staff operations guidance"
 ```
 
 Use `skills guardian list` or `skills admin list` when the needed skill is not obvious. Never substitute one audience for the other. A guardian session cannot fetch the admin catalog; an admin may fetch either catalog.
 
+For machine-readable discovery, use `recess --json agent-context`; for a smaller syntax surface, use `recess --json help <noun> [verb]`. Unknown commands, flags, duplicate non-repeatable flags, missing flag values, and extra positional arguments fail explicitly.
+
 ## Authentication
 
 - Workstation: `recess --json auth login` opens Recess SSO.
@@ -49,23 +51,31 @@ Always pass `--json`. Stdout contains one object:
 - Failure: `{"ok":false,"error":{"code":"...","message":"...","details":{...}}}`, exit 1.
 - Write awaiting approval: `confirmation_required`, exit 2, with `details.preview` and `details.requiredFlag`.
 
+Every command-driven Recess API call except `auth` requires `--reason "..."`: a specific,
+human-readable purpose from 1 to 1024 characters. The server records it in the CLI request audit
+ledger. Reuse the invocation's same reason across its preflight and execution requests. The
+human-only `recess ui` console is exempt.
+
 Every write is two-step:
 
 1. Run without `--confirm`.
 2. Show the human the complete preview, including `preview.details`.
 3. Ask for explicit approval of that exact action.
-4. Rerun the unchanged command with `--confirm`. If the preview includes an `approvalToken`, pass it unchanged.
+4. Rerun the unchanged command with `--confirm --operation-key <operationKey>`. If the preview includes an `approvalToken`, pass it unchanged too.
 
-Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request.
+Any changed target, payload, local file, server revision, amount, recipient, or consequence requires a new preview and new approval. Never infer approval from the original request. If a confirmed invocation is interrupted, retry the unchanged command with the same operation key; never mint a new one for an uncertain write. Inspect recovery state with `recess --json jobs get <operation-key>`.
 
 ## Shared constraints
 
-- Use high-level CLI commands. The raw escape hatch is GET-only: `recess --json request get /path`.
+- Use high-level CLI commands. The raw escape hatch is GET-only:
+  `recess --json request get /path --reason "Inspect the exact API resource needed for this task"`.
 - Resolve names to exact IDs before writes. Stop on ambiguous matches.
 - Money uses integer cents.
 - Keep dates in the exact format required by command help.
 - Treat a 401 or `auth_required` as an authentication problem. A transport-level `fetch failed` is a network/sandbox problem, not proof that the session expired.
-- Run `recess --help` for syntax; load the audience skill for workflow meaning.
+- Use `profile list|save|use` or global `--profile` for named environments. `--deliver file:<path>` atomically stores one JSON envelope locally; authenticated webhook delivery is intentionally unavailable.
+- `feedback submit` records CLI friction under an operation key and optionally forwards it when an upstream endpoint is configured.
+- Run scoped help for syntax; load the audience skill for workflow meaning.
 
 ## Updating this shared skill
 

package/skill/recess-cli/agents/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.0.0",
-  "minCliVersion": "1.6.0"
+  "version": "2.2.0",
+  "minCliVersion": "2.0.0"
 }