@agentwhy/cli 0.2.0 → 0.2.1

package/dist/cli/command-router.js

@@ -3,12 +3,16 @@ const HELP_FLAGS = ['--help', '-h'];
 export class CommandRouter {
     #commands;
     #withoutACommand;
+    #missingCommand;
     /**
      * `withoutACommand` answers `agentwhy` with nothing after it, and with arguments that begin with `-` (they are its
      * flags); without one, that stays a usage error. It may also be registered under its own name.
+     *
+     * `missingCommand` is said under that usage error alone, for whoever ran a bare `agentwhy` where nothing answers it.
      */
-    constructor(commands, withoutACommand) {
+    constructor(commands, withoutACommand, missingCommand) {
         this.#withoutACommand = withoutACommand;
+        this.#missingCommand = missingCommand;
         const byName = new Map();
         for (const command of commands) {
             if (byName.has(command.name))
@@ -27,7 +31,9 @@ export class CommandRouter {
         if (name !== undefined && HELP_FLAGS.includes(name))
             return { kind: 'help', usage: this.usage };
         if (name === undefined) {
-            return this.#withoutACommand === undefined ? this.#usageError('missing command') : this.#withoutACommand.execute([]);
+            if (this.#withoutACommand !== undefined)
+                return this.#withoutACommand.execute([]);
+            return { ...this.#usageError('missing command'), ...(this.#missingCommand === undefined ? {} : { hint: this.#missingCommand }) };
         }
         if (name.startsWith('-') && this.#withoutACommand !== undefined)
             return this.#withoutACommand.execute(argv);

package/dist/cli.js

@@ -71,7 +71,8 @@ function write(result) {
             process.stdout.write(result.usage);
             return EXIT_CODE.ok;
         case 'usage-error':
-            process.stderr.write(`agentwhy: ${result.message}\n\n${result.usage}`);
+            // R73: the message is the first thing on stderr, before any help this one carries.
+            process.stderr.write(`agentwhy: ${result.message}\n\n${result.hint === undefined ? '' : `${result.hint}\n\n`}${result.usage}`);
             return EXIT_CODE.usage;
         case 'completed':
             process.stdout.write(result.output);

package/dist/composition-root.js

@@ -71,6 +71,8 @@ import { ConversationsRenderer } from './report/start/conversations/conversation
 import { SettingsRenderer } from './report/start/settings/settings-renderer.js';
 import { MonthRenderer } from './report/start/month/month-renderer.js';
 import { ToFixRenderer } from './report/start/to-fix/to-fix-renderer.js';
+import { projectName } from './report/start/app-nav.js';
+import { welcomeIn } from './report/start/onboarding/welcome-decision.js';
 import { SessionStart } from './report/start/session-start.js';
 import { NoticeWordsRenderer } from './report/watch/render/notice-words.js';
 import { NoticeSettings } from './report/watch/notice-settings.js';
@@ -393,6 +395,19 @@ export function createCommandRouter(environment) {
         files: start,
         sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
         clock: () => Date.now(),
+        // AW1: the address `--detach` hands over names the welcome where this project is to meet it, as the address a
+        // served run prints does. The same decision the run itself asks (W23), from the same record and settings files.
+        welcome: {
+            file: APP_LINKS.onboarding,
+            project: projectName(environment.workingDirectory),
+            opens: async () => (await welcomeIn(environment.workingDirectory, {
+                store: onboarding,
+                files,
+                home: environment.home,
+                realHome,
+                now: () => Date.now(),
+            })).opens,
+        },
     });
     const start_ = new StartCliCommand({ start, detached, now: environment.now });
     const check_ = new CheckCliCommand({ check, now: environment.now });
@@ -472,5 +487,10 @@ export function createCommandRouter(environment) {
             interactive: environment.inputIsTerminal,
         }),
         new CodexStopCliCommand(codexWatch, environment.inputIsTerminal),
-    ], environment.interactive ? start_ : undefined);
+        // R73 stands (`a-page-not-a-file` PFD3): off a terminal a bare `agentwhy` opens nothing and serves nothing. But the
+        // reader of that refusal is usually an AI agent asked to start agentwhy and send a link, and the usage alone left it
+        // guessing: measured 2026-10-04 in three apps, one guessed `start --detach` and one gave up. So the refusal names it.
+    ], environment.interactive ? start_ : undefined, 'There is no terminal here, so a bare agentwhy opens nothing and serves nothing.\n' +
+        'To serve a page and return at once - what an agent asked to send someone a link needs - run:\n' +
+        '  agentwhy start --detach');
 }

package/dist/report/start/detached-start.js

@@ -1,3 +1,4 @@
+import { printable } from '../../shared/printable.js';
 import { quietlySaid } from './render/start-words.js';
 /**
  * How long a server started in the background is waited for, at most, while its process runs (PF3): its first pages are
@@ -34,12 +35,16 @@ export class DetachedStart {
         }
         return this.#asFiles(options);
     }
-    /** The page asked for on a running server: the session's report where it serves one, else every conversation (SW10). */
+    /**
+     * The page asked for on a running server: the session's report where it serves one (SW10), else the welcome where
+     * this project is to meet it (AW1), else every conversation.
+     */
     async #show(base, options, reused) {
         const { probe, browser } = this.#dependencies;
         const asked = options.session === undefined ? undefined : `${base}${options.session}.html`;
         const found = asked === undefined || (await probe.answers(asked));
-        const url = asked !== undefined && found ? asked : `${base}index.html`;
+        const welcome = await this.#welcome(asked);
+        const url = asked !== undefined && found ? asked : `${base}${welcome?.file ?? 'index.html'}`;
         const opened = options.open && (await browser.open(url));
         // A conversation asked for and not served is said in every output, never passed off as its report (SW10).
         const missing = found ? '' : 'That conversation was not found here, so all conversations are served.\n';
@@ -50,9 +55,23 @@ export class DetachedStart {
             outcome: 'written',
             output: missing +
                 `${reused ? 'agentwhy was already running for this project' : 'agentwhy runs in the background for this project'}: ${url}\n` +
+                // AWD3's sentence, in the words a served run already prints: true whether or not anyone opens the address.
+                (welcome === undefined
+                    ? ''
+                    : `${opened ? 'Opened' : 'That address opens'} the welcome page, to set agentwhy up for ${printable(welcome.project)}.\n`) +
                 'It stops by itself 30 minutes after its last page is closed.\n',
         };
     }
+    /**
+     * AW1: the onboarding's file where this run's address is to name it. A conversation asked for is the person's own
+     * yes to that report and wins over a setup they did not ask for, as a served run's own page does (SW10).
+     */
+    async #welcome(asked) {
+        const { welcome } = this.#dependencies;
+        if (asked !== undefined || welcome === undefined || !(await welcome.opens()))
+            return undefined;
+        return { file: welcome.file, project: welcome.project };
+    }
     /** PF4: no server came up - a sandbox, a refusal - so the pages are files, and what would serve them is said. */
     async #asFiles(options) {
         const written = await this.#dependencies.files.run({ ...options, serve: false });

package/dist/report/start/onboarding/welcome-decision.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { join } from 'node:path';
+import { SETTINGS_FILES } from '../../../adapter/claude-code/contract/settings.js';
+import { notAProject } from '../../../setup/not-a-project.js';
+import { readSettingsFile, setUpBy } from '../settings-files.js';
+/**
+ * Whether a project's run should name the onboarding instead of the index (W23), and what else the page needs to know.
+ *
+ * Its one side effect is N6's: a project set up before this screen existed, or by hand, has its `done` line written
+ * here and silently, so that turning alerts off later never brings the onboarding back. Asking a second time for the
+ * same project writes no second line: that reading finds the first.
+ *
+ * Shared by every run that names a page - `start` itself, and `start --detach`, whose address is the only way a person
+ * reaches one (`2026-10-01-the-address-opens-the-welcome.md` AW1, extended to `--detach` on 2026-10-04).
+ */
+export async function welcomeIn(workingDirectory, asked) {
+    const { store, files, home, realHome, now } = asked;
+    const reading = await store.read();
+    // W24: the intro plays once per person - where no project of theirs has finished the onboarding.
+    const intro = !reading.anywhere && !reading.failed;
+    // which-project V7: in the home directory no project is being shown, so the onboarding opens at its project step,
+    // whatever the record says - after the welcome only for a person who has never finished one. Nothing here is set up
+    // and no record is kept of it: not even the silent `done` line below.
+    if (home !== undefined && notAProject(workingDirectory, home, realHome) !== undefined) {
+        return { opens: true, intro, setUp: false, ...(intro ? {} : { atProject: true }) };
+    }
+    if (reading.here)
+        return { opens: false, intro, setUp: true };
+    if (reading.failed)
+        return { opens: false, intro, setUp: false };
+    // A local file that cannot be read leaves what runs unknown, and the onboarding closed (as `#settingsNow` does).
+    const local = await readSettingsFile(files, join(workingDirectory, SETTINGS_FILES.directory, SETTINGS_FILES.local));
+    if (local === 'unreadable')
+        return { opens: false, intro, setUp: false };
+    const shared = await readSettingsFile(files, join(workingDirectory, SETTINGS_FILES.directory, SETTINGS_FILES.shared));
+    // N6, widened 2026-09-28 by the maintainer (which-project V10): a project where one of agentwhy's hooks runs, or whose
+    // settings block files, was set up - before this screen existed, or by hand - and is recorded so, silently.
+    if (setUpBy([local, shared])) {
+        await store.add(now());
+        return { opens: false, intro, setUp: true };
+    }
+    return { opens: true, intro, setUp: false };
+}

package/dist/report/start/render/start-words.js

@@ -75,7 +75,12 @@ function page(said, view) {
         ...(said.welcome === 'opened' ? [`Opened the welcome page, to set agentwhy up for ${said.project ?? 'this project'}.`] : []),
         ...(said.welcome === 'served' ? [`That address opens the welcome page, to set agentwhy up for ${said.project ?? 'this project'}.`] : []),
         ...(said.servedAsFile === true
-            ? [warn('The page could not be served, so it was opened as a file: marks made on it are copied as commands.', view)]
+            ? [
+                warn('The page could not be served, so it was opened as a file: marks made on it are copied as commands.', view),
+                // PF4's way out, which `--detach` has always said and this run did not: a sandbox is the usual reason, and a
+                // person reading a file cannot finish a setup or make a mark on it.
+                dim('To open it live, run this command again outside the sandbox, or type npx @agentwhy/cli in a terminal.', view),
+            ]
             : []),
         dim(said.shared
             ? 'Shared view: session ids and the project path are not shown, and nothing above the project root appears in any report.'

package/dist/report/start/session-start.js

@@ -19,7 +19,7 @@ import { indexHandler } from './serve/index-handler.js';
 import { movedPage } from './projects/moved-page.js';
 import { nearestProject } from '../../core/nearest-project.js';
 import { translator } from '../render/report-copy.js';
-import { hookComplete, readSettingsFile, setUpBy } from './settings-files.js';
+import { hookComplete, readSettingsFile } from './settings-files.js';
 import { indexProjects } from './projects/index-projects.js';
 import { NOT_A_PROJECT } from '../../setup/project-setup.js';
 import { notAProject } from '../../setup/not-a-project.js';
@@ -31,6 +31,7 @@ import { DEFAULT_THRESHOLD } from '../watch/agent-alert.js';
 import { DEFAULT_CHANNELS, DEFAULT_CLEAN, DEFAULT_SAID_AS } from '../watch/notice-choices.js';
 import { actionsAfterMarks, markLines, marksInRange, standingMarks } from '../check/marks.js';
 import { finishOnboarding } from './onboarding/finish-onboarding.js';
+import { welcomeIn } from './onboarding/welcome-decision.js';
 import { WHO_STEP } from './onboarding/onboarding-script.js';
 import { repositoryAbove } from './repository.js';
 import { pageStopped, quietlySaid, startSaid } from './render/start-words.js';
@@ -684,33 +685,17 @@ export class SessionStart {
      * alerts off later never brings the onboarding back.
      */
     async #welcome(workingDirectory) {
-        const { onboarding, setup, notices } = this.#dependencies;
+        const { onboarding, setup, notices, policyFiles, home, realHome } = this.#dependencies;
+        // The onboarding writes through both (W15), so a run without them names no page it could not finish.
         if (onboarding === undefined || setup === undefined || notices === undefined)
             return undefined;
-        const reading = await onboarding.store.read();
-        // W24: the intro plays once per person - where no project of theirs has finished the onboarding.
-        const intro = !reading.anywhere && !reading.failed;
-        // which-project V7: in the home directory no project is being shown, so the onboarding opens at its project step,
-        // whatever the record says - after the welcome only for a person who has never finished one. Nothing here is set up
-        // and no record is kept of it: not even the silent `done` line below.
-        if (this.#notAProject(workingDirectory) !== undefined)
-            return { opens: true, intro, setUp: false, ...(intro ? {} : { atProject: true }) };
-        if (reading.here)
-            return { opens: false, intro, setUp: true };
-        if (reading.failed)
-            return { opens: false, intro, setUp: false };
-        // A local file that cannot be read leaves what runs unknown, and the onboarding closed (as `#settingsNow` does).
-        const local = await this.#settingsFile(join(workingDirectory, SETTINGS_FILES.directory, SETTINGS_FILES.local));
-        if (local === 'unreadable')
-            return { opens: false, intro, setUp: false };
-        const shared = await this.#settingsFile(join(workingDirectory, SETTINGS_FILES.directory, SETTINGS_FILES.shared));
-        // N6, widened 2026-09-28 by the maintainer (which-project V10): a project where one of agentwhy's hooks runs, or whose
-        // settings block files, was set up - before this screen existed, or by hand - and is recorded so, silently.
-        if (setUpBy([local, shared])) {
-            await onboarding.store.add((this.#dependencies.clock ?? (() => this.#dependencies.now))());
-            return { opens: false, intro, setUp: true };
-        }
-        return { opens: true, intro, setUp: false };
+        return welcomeIn(workingDirectory, {
+            store: onboarding.store,
+            files: policyFiles,
+            ...(home === undefined ? {} : { home }),
+            ...(realHome === undefined ? {} : { realHome }),
+            now: this.#dependencies.clock ?? (() => this.#dependencies.now),
+        });
     }
     /**
      * The person's projects, read again with every refresh as the settings are, since a project set up in another tab is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentwhy/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Reconstructs from transcripts why an AI agent reached for protected data",
   "type": "module",
   "license": "Apache-2.0",