@agentwhy/cli 0.2.0 → 0.3.0

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/render/ui/fold-line.js

@@ -21,4 +21,6 @@ export const FOLD_LINE_STYLE = String.raw `
 .fold-hide{display:none}.fold[open] .fold-hide{display:inline}.fold[open] .fold-show{display:none}
 .fold-sand>.fold-line{border:1px solid var(--sand-35);background:var(--card)}.fold-sand>.fold-line:hover{border-color:var(--sand)}
 .fold-sand .fold-mark{width:32px;height:32px;background:var(--sand-16);color:var(--sand)}.fold-sand .fold-mark svg{width:16px;height:16px}
+.fold-grey>.fold-line{border:1px solid var(--white-16);background:var(--card)}.fold-grey>.fold-line:hover{border-color:var(--white-32)}
+.fold-grey .fold-mark{width:32px;height:32px;background:var(--white-10);color:var(--text-2);font-size:15px}
 `;

package/dist/report/render/ui/popup.js

@@ -28,7 +28,7 @@ dialog.pp-wide{isolation:isolate}
 html:not(.js) dialog.pp-wide:target{position:relative}
 dialog.pp::backdrop{background:var(--backdrop);backdrop-filter:blur(6px);-webkit-backdrop-filter:blur(6px)}
 dialog.pp-wizard{max-width:640px;margin-top:56px;max-height:calc(100vh - 112px)}
-dialog.pp-list{max-width:800px;margin-top:56px;max-height:calc(100vh - 112px)}
+dialog.pp-list{max-width:920px;margin-top:56px;max-height:calc(100vh - 112px)}
 dialog.pp-small,dialog.pp-pick,dialog.pp-confirm{border-color:var(--white-10);border-radius:20px;margin:auto}
 dialog.pp-small{max-width:560px}dialog.pp-pick{max-width:520px}dialog.pp-confirm{max-width:460px}
 html:not(.js) dialog.pp:target{display:block;position:static;margin:24px auto;max-height:none}

package/dist/report/render/ui/project-list.js

@@ -1,5 +1,5 @@
 import { escapeHtml as e } from '../html-report-components.js';
-import { inLanguages, LANGS, translator } from '../report-copy.js';
+import { inLanguages, labelAttributes, LANGS, translator } from '../report-copy.js';
 import { initial } from './app-sidebar.js';
 import { dayName, localClock } from './local-date.js';
 import { tag } from './tag.js';
@@ -29,19 +29,20 @@ export function projectList(spec) {
         return pickList(spec, spec.pick, when);
     const action = spec.action;
     const row = (one) => '<li class="pjl-row"' + searchable(one) + '>' + cells(one, when, action) + '</li>';
-    return '<div class="pjl">' +
+    return '<div class="pjl" data-order="new">' +
         (here === undefined ? '' :
             '<p class="pjl-label">' + inLanguages((t) => t('proj.here')) + '</p>' +
                 '<div class="pjl-here' + (here.setUp === true ? ' pjl-here-set' : '') + '">' + cells(here, when, action) + '</div>') +
-        '<div class="pjl-label-line"><p class="pjl-label">' + inLanguages((t) => t('proj.others')) + '</p>' +
-        (others.length + gone.length === 0 ? '' : search()) + '</div>' +
+        '<div class="pjl-label-line"><p class="pjl-label">' +
+        ['new', 'az', 'za'].map((order) => '<span class="pjl-order pjl-order-' + order + '">' + inLanguages((t) => t(order === 'new' ? 'proj.others' : 'proj.others.' + order)) + '</span>').join('') +
+        '</p>' + (others.length + gone.length === 0 ? '' : search()) + '</div>' +
         '<p class="pjl-none" data-search-none hidden></p>' +
         (shown.length === 0 && gone.length === 0
             ? '<p class="pjl-none">' + inLanguages((t) => t('proj.none')) + '</p>'
             : '<div class="pjl-table">' +
                 (shown.length === 0 ? '' :
-                    '<div class="pjl-heads" aria-hidden="true"><span></span><span>' + inLanguages((t) => t('proj.col.project')) + '</span>' +
-                        '<span>' + inLanguages((t) => t('proj.col.status')) + '</span><span></span></div>' +
+                    '<div class="pjl-heads"><span aria-hidden="true"></span><span>' + sortByName() + '</span>' +
+                        '<span aria-hidden="true">' + inLanguages((t) => t('proj.col.status')) + '</span><span aria-hidden="true"></span></div>' +
                         '<ul class="pjl-rows">' + shown.map(row).join('') + '</ul>') +
                 (gone.length === 0 ? '' :
                     '<details class="pjl-gone"><summary class="pjl-gone-line"><span>' + inLanguages((t) => t('proj.goneFold', { n: gone.length })) + '</span>' +
@@ -122,6 +123,18 @@ function search() {
     return '<input type="search" class="pjl-search js-only" data-project-search autocomplete="off" spellcheck="false"' +
         ' aria-label="' + e(translator('en')('proj.search')) + '" data-search-words="' + e(JSON.stringify(words)) + '">';
 }
+/**
+ * A-Z, Z-A, or newest first (the maintainer, 2026-10-05): the head of the Project column is the button that cycles the
+ * three, with the order it is in drawn beside the word - up for A-Z, down for Z-A, both ways for the order the list
+ * came in. Only a script can sort, so only a page with one offers it, and a page without one keeps the plain word; the
+ * line above the table says the order in words, so what changed is never only a glyph.
+ */
+function sortByName() {
+    return '<button type="button" class="pjl-sort js-only" data-pjl-sort' + labelAttributes((t) => t('proj.sort')) + '>' +
+        inLanguages((t) => t('proj.col.project')) + '<span class="pjl-sort-mark" aria-hidden="true">' +
+        ['new', 'az', 'za'].map((order, at) => '<span class="pjl-order pjl-order-' + order + '">' + ['\u2195', '\u2191', '\u2193'][at] + '</span>').join('') +
+        '</span></button><span class="nojs-only" aria-hidden="true">' + inLanguages((t) => t('proj.col.project')) + '</span>';
+}
 /**
  * A row's radio, in the column where the window offers **Open**: a real one, so the keys move between the rows as they do
  * in any group. What the page chooses by is the id, never a path (V17). The row chosen is mint, not coral (the
@@ -131,9 +144,9 @@ function radio(group, row) {
     return '<input type="radio" class="pjl-radio-input" name="' + e(group) + '" value="' + e(row.id) + '" data-pick-name="' + e(row.name) + '"' +
         (row.current ? ' data-pick-here checked' : '') + '><span class="pjl-radio" aria-hidden="true"><span class="pjl-radio-dot"></span></span>';
 }
-/** What the field matches a row by: its name and where it is, in lower case. */
+/** What the field matches a row by: its name and where it is, in lower case - and the name alone, what it sorts by. */
 function searchable(row) {
-    return ' data-search="' + e((row.name + ' ' + row.place).toLowerCase()) + '"';
+    return ' data-search="' + e((row.name + ' ' + row.place).toLowerCase()) + '" data-sort-name="' + e(row.name.toLowerCase()) + '"';
 }
 /** A row's four cells: the folder's initial, the project, its status, and what it offers. */
 function cells(row, when, action) {
@@ -166,8 +179,15 @@ export const PROJECT_LIST_STYLE = String.raw `
 .pjl{--pjl-columns:44px minmax(0,1fr) 172px 128px}
 .pjl-label{margin:22px 4px 10px;font-size:13.5px;font-weight:600;color:var(--text-3)}
 .pjl-label:first-child{margin-top:4px}
-.pjl-label-line{display:flex;align-items:flex-end;justify-content:space-between;gap:12px}
-.pjl-label-line .pjl-label{margin-top:22px}
+.pjl-label-line{display:flex;align-items:flex-end;justify-content:space-between;gap:12px;margin-top:34px}
+.pjl-label-line .pjl-label{margin-top:0}
+.pjl-order{display:none}
+.pjl[data-order="new"] .pjl-order-new,.pjl[data-order="az"] .pjl-order-az,.pjl[data-order="za"] .pjl-order-za{display:inline}
+.pjl-sort{display:inline-flex;align-items:center;gap:7px;margin:-4px 0;padding:4px 8px;border:0;border-radius:8px;background:none;font:inherit;font-size:12.5px;font-weight:600;color:var(--text-3);cursor:pointer}
+.pjl-sort:hover{color:var(--text);background:var(--white-05)}
+.pjl-sort:focus-visible{outline:2px solid var(--coral);outline-offset:1px}
+.pjl-sort-mark{font-size:12px;line-height:1;opacity:.75}
+.pjl-sort:hover .pjl-sort-mark{opacity:1}
 .pjl-search{width:200px;margin:0 0 8px;padding:7px 12px;border-radius:999px;border:1px solid var(--white-14);background:var(--card);color:var(--text);font:inherit;font-size:13.5px}
 .pjl-search::placeholder{color:var(--text-3)}
 .pjl-search:focus{outline:none;border-color:var(--white-32)}
@@ -248,6 +268,25 @@ export const PROJECT_LIST_SCRIPT = String.raw `
     const list = button.closest('.pjl');
     if (list) list.classList.remove('pjl-folded');
   }));
+  // A-Z, Z-A, newest first: the order the rows came in is kept, so the third press is not a guess at it.
+  document.querySelectorAll('[data-pjl-sort]').forEach((button) => {
+    const list = button.closest('.pjl');
+    if (!list) return;
+    const after = { new: 'az', az: 'za', za: 'new' };
+    const groups = [...list.querySelectorAll('.pjl-table .pjl-rows')].map((rows) => ({ rows, came: [...rows.children] }));
+    button.addEventListener('click', () => {
+      const order = after[list.dataset.order] || 'az';
+      list.dataset.order = order;
+      groups.forEach(({ rows, came }) => {
+        const put = came.slice();
+        if (order !== 'new') {
+          const way = order === 'az' ? 1 : -1;
+          put.sort((one, two) => way * String(one.dataset.sortName || '').localeCompare(String(two.dataset.sortName || '')));
+        }
+        put.forEach((row) => rows.appendChild(row));
+      });
+    });
+  });
   document.querySelectorAll('[data-project-search]').forEach((input) => {
     const list = input.closest('.pjl');
     if (!list) return;

package/dist/report/render/ui/words/conversations-words.js

@@ -68,6 +68,10 @@ export const CONVERSATIONS_WORDS = {
         'conv.unchecked.partial.title.other': '{n} conversations couldn’t be fully checked.',
         'conv.unchecked.partial': 'Their record leaves out some steps, so their reports may not show everything your AI opened. Open one to see what was written down.',
         'conv.unchecked.mixed': 'Some are older than this check, or their record couldn’t be opened. The others leave out some steps, so their reports may not show everything. To include older ones, run {command}',
+        'conv.unchecked.lead.rest': '— older than this check, or their record couldn’t be read.',
+        'conv.unchecked.check.rest': '— not read yet.',
+        'conv.unchecked.partial.rest': '— read, but their record has gaps.',
+        'conv.unchecked.mixed.rest': '— some older than this check, the rest read with gaps.',
         'conv.act.fix': 'Fix it →',
         'conv.act.see': 'See report',
         'conv.act.none': 'No report',
@@ -226,6 +230,10 @@ export const CONVERSATIONS_WORDS = {
         'conv.unchecked.partial.title.many': '{n} rozmów nie zostało w pełni sprawdzonych.',
         'conv.unchecked.partial': 'Ich zapis pomija niektóre kroki, więc raporty mogą nie pokazywać wszystkiego, co otworzyło twoje AI. Otwórz którąś, żeby zobaczyć, co zostało zapisane.',
         'conv.unchecked.mixed': 'Część jest starsza niż to sprawdzenie albo nie dało się otworzyć ich zapisu. Zapis pozostałych pomija niektóre kroki, więc raporty mogą nie pokazywać wszystkiego. Żeby dołączyć starsze, uruchom {command}',
+        'conv.unchecked.lead.rest': '— starsze niż to sprawdzenie albo nie dało się odczytać ich zapisu.',
+        'conv.unchecked.check.rest': '— jeszcze nieprzeczytane.',
+        'conv.unchecked.partial.rest': '— przeczytane, ale ich zapis ma luki.',
+        'conv.unchecked.mixed.rest': '— część starsza niż to sprawdzenie, reszta przeczytana z lukami.',
         'conv.act.fix': 'Napraw →',
         'conv.act.see': 'Zobacz raport',
         'conv.act.none': 'Brak raportu',
@@ -376,6 +384,10 @@ export const CONVERSATIONS_WORDS = {
         'conv.unchecked.partial.title.other': '{n} Unterhaltungen konnten nicht vollständig geprüft werden.',
         'conv.unchecked.partial': 'Ihre Aufzeichnung lässt einige Schritte aus, daher zeigen ihre Berichte vielleicht nicht alles, was deine KI geöffnet hat. Öffne eine, um zu sehen, was aufgezeichnet wurde.',
         'conv.unchecked.mixed': 'Einige sind älter als diese Prüfung, oder ihre Aufzeichnung ließ sich nicht öffnen. Die übrigen lassen einige Schritte aus, daher zeigen ihre Berichte vielleicht nicht alles. Um ältere einzubeziehen, führe {command} aus',
+        'conv.unchecked.lead.rest': '— älter als diese Prüfung, oder ihre Aufzeichnung war nicht lesbar.',
+        'conv.unchecked.check.rest': '— noch nicht gelesen.',
+        'conv.unchecked.partial.rest': '— gelesen, aber ihre Aufzeichnung hat Lücken.',
+        'conv.unchecked.mixed.rest': '— einige älter als diese Prüfung, die übrigen mit Lücken gelesen.',
         'conv.act.fix': 'Beheben →',
         'conv.act.see': 'Bericht ansehen',
         'conv.act.none': 'Kein Bericht',

package/dist/report/render/ui/words/projects-words.js

@@ -9,6 +9,9 @@ export const PROJECTS_WORDS = {
         'proj.lead': 'Pick the project you want agentwhy to watch.',
         'proj.here': 'You’re here now',
         'proj.others': 'Other projects · newest first',
+        'proj.others.az': 'Other projects · A–Z',
+        'proj.others.za': 'Other projects · Z–A',
+        'proj.sort': 'Sort projects by name',
         'proj.yours': 'Your projects · newest first',
         'moved.pageTitle': 'Another project · agentwhy',
         'moved.title': 'This page was for {was}.',
@@ -76,6 +79,9 @@ export const PROJECTS_WORDS = {
         'proj.lead': 'Wybierz projekt, który agentwhy ma obserwować.',
         'proj.here': 'Jesteś tutaj',
         'proj.others': 'Inne projekty · od najnowszych',
+        'proj.others.az': 'Inne projekty · A–Z',
+        'proj.others.za': 'Inne projekty · Z–A',
+        'proj.sort': 'Sortuj projekty po nazwie',
         'proj.yours': 'Twoje projekty · od najnowszych',
         'moved.pageTitle': 'Inny projekt · agentwhy',
         'moved.title': 'Ta strona była dla projektu {was}.',
@@ -152,6 +158,9 @@ export const PROJECTS_WORDS = {
         'proj.lead': 'Wähle das Projekt, das agentwhy beobachten soll.',
         'proj.here': 'Hier bist du gerade',
         'proj.others': 'Andere Projekte · die neuesten zuerst',
+        'proj.others.az': 'Andere Projekte · A–Z',
+        'proj.others.za': 'Andere Projekte · Z–A',
+        'proj.sort': 'Projekte nach Name sortieren',
         'proj.yours': 'Deine Projekte · die neuesten zuerst',
         'moved.pageTitle': 'Anderes Projekt · agentwhy',
         'moved.title': 'Diese Seite war für {was}.',

package/dist/report/start/conversations/period-section.js

@@ -78,12 +78,7 @@ export function periodSection(periods, at, index, spec) {
                 dataTable({ ...CONVERSATION_TABLE, rows: fix.map((item) => conversationRow(item, index.widen, !index.shared)) }) +
                 '</section>') +
         (!spec.lists || info.length === 0 ? '' : forYourInfo(info, index)) +
-        (!spec.lists || unchecked.length === 0 ? '' :
-            '<section class="cw-need cw-unchecked" data-need><div class="cw-need-head"><span class="cw-need-dot" aria-hidden="true"></span>' +
-                '<h2 class="cw-h2">' + inLanguages((t) => t(partial ? 'look.unchecked' : 'conv.unchecked')) + '</h2><span class="cw-need-count" data-need-count>' + unchecked.length + '</span></div>' +
-                '<p class="cw-unchecked-lead">' + inLanguages((t) => t(lead, { command: '<code>' + e(index.widen) + '</code>' })) + '</p>' +
-                dataTable({ ...CONVERSATION_TABLE, rows: unchecked.map((item) => conversationRow(item, index.widen, !index.shared)) }) +
-                '</section>') +
+        (!spec.lists || unchecked.length === 0 ? '' : notFullyChecked(unchecked, partial, lead, index)) +
         (!spec.lists || others.length === 0 ? '' : theRest(others, need.length === 0, index)) +
         '</section>';
 }
@@ -101,6 +96,27 @@ function forYourInfo(info, index) {
         body: dataTable({ ...CONVERSATION_TABLE, rows: info.map((item) => conversationRow(item, index.widen, !index.shared)) }),
     }) + '</section>';
 }
+/**
+ * "Couldn't check fully (n)" (the maintainer, 2026-10-05): what this run could not read, or read with gaps, in a fold
+ * of its own - a solid grey line with the look's ?, shut, and opened with **Show**. Every Codex record has a gap
+ * (`2026-09-27-what-codex-wrote.md` X23), so on a project worked in with Codex this list holds the whole week, asks
+ * for nothing, and was the longest thing on the page; the maintainer asked for it shut on arrival (2026-10-05), not
+ * only shuttable. Shut it still says all of it the page owes: the heading, how many, and in brief why - and the
+ * period's card above says the number too. The sentence of the reason and the command that would include them go
+ * inside, with the rows; the list is still apart from what is to fix and is never a group of the rest's table
+ * (F17, F13, O4). The script narrows it to the day chosen as it does the other lists (`data-need`), and the count it
+ * rewrites is the one in the line, which is in view whether the fold is open or not.
+ */
+function notFullyChecked(unchecked, partial, lead, index) {
+    return '<section class="cw-need cw-unchecked" data-need>' + foldLine({
+        summary: '<strong>' + inLanguages((t) => t(partial ? 'look.unchecked' : 'conv.unchecked')) +
+            ' (<span data-need-count>' + unchecked.length + '</span>)</strong> <span class="fold-rest">' +
+            inLanguages((t) => t(lead + '.rest')) + '</span>',
+        mark: { glyph: LOOKS.unchecked.glyph, tone: 'grey' },
+        body: '<p class="cw-unchecked-lead">' + inLanguages((t) => t(lead, { command: '<code>' + e(index.widen) + '</code>' })) + '</p>' +
+            dataTable({ ...CONVERSATION_TABLE, rows: unchecked.map((item) => conversationRow(item, index.widen, !index.shared)) }),
+    }) + '</section>';
+}
 /** The looks of the rest, in the order of F16's ladder: the groups of F13 and F14, and the order they are listed in. */
 const REST = ['fixed', 'name', 'stopped', 'none'];
 /** A group's table rows past this many wait behind "Show all" while the whole period is shown (F14). */
@@ -237,8 +253,7 @@ export const PERIOD_SECTION_STYLE = String.raw `
 .cw-need-head{display:flex;align-items:baseline;gap:10px;margin-bottom:12px}
 .cw-need-dot{width:10px;height:10px;border-radius:50%;background:var(--coral);align-self:center}
 .cw-need-count{font-size:15px;font-weight:650;color:var(--coral-text)}
-.cw-unchecked .cw-need-dot{background:var(--text-3)}.cw-unchecked .cw-need-count{color:var(--text-2)}
-.cw-unchecked-lead{margin:-4px 0 12px;font-size:14px;line-height:1.5;color:var(--text-2)}
+.cw-unchecked-lead{margin:0 0 12px;font-size:14px;line-height:1.5;color:var(--text-2)}
 .cw-unchecked-lead code,.guide code{font-family:var(--mono);font-size:13px;color:var(--text);background:var(--white-07);border-radius:6px;padding:1px 6px}
 .cw-tools{display:none;gap:10px;flex-wrap:wrap;align-items:center;margin-bottom:16px}
 .js .cw-tools{display:flex}

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.3.0",
   "description": "Reconstructs from transcripts why an AI agent reached for protected data",
   "type": "module",
   "license": "Apache-2.0",