@reticlehq/init 3.5.0 → 3.7.0

package/dist/detect/detect.d.ts

@@ -194,6 +194,14 @@ export declare const ANGULAR_WORKSPACE_FILE = "angular.json";
 interface FrameworkSignals {
     /** `package.json` dependency names that name this framework outright. */
     readonly deps: readonly string[];
+    /**
+     * Dependencies that disprove this framework's dependency signal, without affecting an explicit
+     * config-file signal.
+     *
+     * Vinext carries `next` for API compatibility but builds through Vite, so treating `next` as
+     * conclusive there would install wiring that Vinext never evaluates.
+     */
+    readonly depsUnless?: readonly string[];
     /** Root config-file basenames that name it when the dependency is absent. */
     readonly configs: readonly string[];
     /**

package/dist/detect/detect.js

@@ -164,7 +164,7 @@ const VITE_INDEX_HTML = 'index.html';
  * asserted in `framework-adapter.test.ts`.
  */
 export const FRAMEWORK_SIGNALS = {
-    [Framework.NEXT]: { deps: ['next'], configs: NEXT_CONFIGS },
+    [Framework.NEXT]: { deps: ['next'], depsUnless: ['vinext'], configs: NEXT_CONFIGS },
     [Framework.NUXT]: { deps: ['nuxt'], configs: NUXT_CONFIGS },
     [Framework.SVELTEKIT]: {
         deps: ['@sveltejs/kit'],
@@ -201,7 +201,7 @@ export const FRAMEWORK_SIGNALS = {
         deps: ['@tanstack/react-start', '@tanstack/start'],
         configs: [],
     },
-    [Framework.VITE]: { deps: ['vite'], configs: VITE_CONFIGS },
+    [Framework.VITE]: { deps: ['vite', 'vinext'], configs: VITE_CONFIGS },
     /** CRA has no config file at all, so the dependency is the only signal. */
     [Framework.CRA]: { deps: ['react-scripts'], configs: [] },
     /** Nothing identifies plain HTML; it is where the chain below ends. */
@@ -325,8 +325,11 @@ function declaredDependencies(pkg) {
 function detectFramework(input) {
     for (const framework of DETECTION_ORDER) {
         const signals = FRAMEWORK_SIGNALS[framework];
-        if (signals.deps.some((d) => depVersion(input.pkg, d) !== undefined))
+        const hasDisqualifyingDependency = true === signals.depsUnless?.some((d) => depVersion(input.pkg, d) !== undefined);
+        if (signals.deps.some((d) => depVersion(input.pkg, d) !== undefined) &&
+            !hasDisqualifyingDependency) {
             return framework;
+        }
         if (hasAnyConfig(input.configFiles, signals.configs) &&
             !hasAnyConfig(input.configFiles, signals.configsUnless ?? [])) {
             return framework;

package/dist/detect/dev-script.d.ts

@@ -1,3 +1,4 @@
+import type { InitIo } from '../run-types.js';
 /**
  * Which command starts this project, and should we start it ourselves?
  *
@@ -72,4 +73,20 @@ export declare function desktopLaunch(pkg: unknown): DesktopLaunch | undefined;
 export declare function devCommandFrom(pkg: unknown, packageManagerCommand: string): string | undefined;
 /** The dev script's own command line (`react-router dev`, `vite`), or undefined when there is none. */
 export declare function devScriptBody(pkg: unknown): string | undefined;
+interface ViteConfigDiscovery {
+    config: {
+        path: string;
+        source: string;
+    } | null;
+    /** Paths that may own Vite but cannot safely be selected automatically. */
+    candidates: readonly string[];
+}
+/**
+ * Find the config that a plain-Vite dev script actually loads.
+ *
+ * An explicit `--config` is authoritative. A direct `vite` command without one keeps Vite's own
+ * root lookup. A custom server with no root config but nested ones is ambiguous, so it returns
+ * evidence for a precise MANUAL step instead of creating a root config the server may never read.
+ */
+export declare function discoverPlainViteConfig(io: InitIo, pkg: unknown, rootFiles: ReadonlySet<string>, configNames: readonly string[]): ViteConfigDiscovery;
 export {};

package/dist/detect/dev-script.js

@@ -137,3 +137,131 @@ export function devScriptBody(pkg) {
     const body = name === undefined ? undefined : table[name];
     return 'string' === typeof body ? body : undefined;
 }
+const SHELL_TOKEN = /"(?:\\.|[^"\\])*"|'[^']*'|&&|\|\||[;|]|[^\s;&|]+/g;
+const SHELL_SEPARATORS = new Set(['&&', '||', ';', '|']);
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const MAX_CONFIG_DEPTH = 4;
+const MAX_CONFIG_CANDIDATES = 20;
+const SKIP_CONFIG_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'out',
+    'coverage',
+    'target',
+    '.git',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+]);
+function unquote(token) {
+    if (token.startsWith("'") && token.endsWith("'"))
+        return token.slice(1, -1);
+    if (token.startsWith('"') && token.endsWith('"')) {
+        return token.slice(1, -1).replace(/\\(["\\])/g, '$1');
+    }
+    return token;
+}
+function safeRelativePath(value) {
+    const normal = unquote(value).replace(/\\/g, '/').replace(/^\.\//, '');
+    if ('' === normal ||
+        normal.startsWith('/') ||
+        normal.startsWith('~') ||
+        /^[A-Za-z]:\//.test(normal) ||
+        normal.split('/').includes('..') ||
+        /[\0$`]/.test(normal)) {
+        return null;
+    }
+    return normal;
+}
+function isViteCommand(token) {
+    const normal = token.replace(/\\/g, '/');
+    return 'vite' === normal || 'vite.cmd' === normal || normal.endsWith('/node_modules/.bin/vite');
+}
+/** The direct Vite invocation in the selected dev script, if that script has one. */
+function viteInvocation(script) {
+    const tokens = script.match(SHELL_TOKEN) ?? [];
+    let start = 0;
+    while (start < tokens.length) {
+        let end = start;
+        while (end < tokens.length && !SHELL_SEPARATORS.has(tokens[end] ?? ''))
+            end += 1;
+        const segment = tokens.slice(start, end).map(unquote);
+        let command = 0;
+        while (command < segment.length && ENV_ASSIGNMENT.test(segment[command] ?? ''))
+            command += 1;
+        if (isViteCommand(segment[command] ?? '')) {
+            const args = segment.slice(command + 1);
+            for (let i = 0; i < args.length; i += 1) {
+                const arg = args[i] ?? '';
+                const inline = /^(?:--config|-c)=(.*)$/.exec(arg);
+                const raw = inline?.[1] ?? ('--config' === arg || '-c' === arg ? args[i + 1] : undefined);
+                if (raw !== undefined) {
+                    return { configArgument: raw, configPath: safeRelativePath(raw) };
+                }
+            }
+            return { configArgument: null, configPath: null };
+        }
+        start = end + 1;
+    }
+    return undefined;
+}
+function nestedViteConfigs(io, configNames) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (found.length >= MAX_CONFIG_CANDIDATES || depth > MAX_CONFIG_DEPTH)
+            return;
+        for (const file of io.listFiles(dir)) {
+            if (configNames.includes(file))
+                found.push(`${dir}/${file}`);
+            if (found.length >= MAX_CONFIG_CANDIDATES)
+                return;
+        }
+        for (const child of io.listDirs(dir)) {
+            if (found.length >= MAX_CONFIG_CANDIDATES)
+                return;
+            if (child.startsWith('.') || SKIP_CONFIG_DIRS.has(child))
+                continue;
+            walk(`${dir}/${child}`, depth + 1);
+        }
+    };
+    for (const dir of io.listDirs('.')) {
+        if (found.length >= MAX_CONFIG_CANDIDATES)
+            break;
+        if (dir.startsWith('.') || SKIP_CONFIG_DIRS.has(dir))
+            continue;
+        walk(dir, 1);
+    }
+    return [...new Set(found)];
+}
+function readable(io, path) {
+    if (null === path)
+        return null;
+    const source = io.readFile(path);
+    return null === source ? null : { path, source };
+}
+/**
+ * Find the config that a plain-Vite dev script actually loads.
+ *
+ * An explicit `--config` is authoritative. A direct `vite` command without one keeps Vite's own
+ * root lookup. A custom server with no root config but nested ones is ambiguous, so it returns
+ * evidence for a precise MANUAL step instead of creating a root config the server may never read.
+ */
+export function discoverPlainViteConfig(io, pkg, rootFiles, configNames) {
+    const rootPath = configNames.find((path) => rootFiles.has(path)) ?? null;
+    const script = devScriptBody(pkg);
+    const invocation = script === undefined ? undefined : viteInvocation(script);
+    if (invocation !== undefined && invocation.configArgument !== null) {
+        const config = readable(io, invocation.configPath);
+        return {
+            config,
+            candidates: null === config ? [invocation.configArgument] : [],
+        };
+    }
+    if (invocation !== undefined)
+        return { config: readable(io, rootPath), candidates: [] };
+    const nested = script === undefined ? [] : nestedViteConfigs(io, configNames);
+    if (null === rootPath && nested.length > 0) {
+        return { config: null, candidates: nested };
+    }
+    return { config: readable(io, rootPath), candidates: [] };
+}

package/dist/detect/non-js-project.d.ts

@@ -34,6 +34,22 @@ export declare function detectDjangoProject(exists: (file: string) => boolean, r
 export declare function djangoSetupMessage(): string;
 /** The ecosystem this directory looks like, or undefined when nothing says. */
 export declare function detectNonJsEcosystem(exists: (file: string) => boolean): string | undefined;
+/** Which answer `init` gives when there is no package.json. */
+export declare const NoPackageJsonCase: {
+    /** No ecosystem marker and no page: the only honest answer is "run `init` somewhere else". */
+    readonly WRONG_DIRECTORY: "wrong_directory";
+    /** A page with no build step, which takes the script-tag snippet. */
+    readonly STATIC_PAGE: "static_page";
+    /** Flutter web paints into a canvas, so there is nothing to instrument. */
+    readonly FLUTTER: "flutter";
+    /** A recognised non-JS ecosystem, which can load the SDK from a URL. */
+    readonly NON_JS: "non_js";
+};
+export type NoPackageJsonCase = (typeof NoPackageJsonCase)[keyof typeof NoPackageJsonCase];
+export interface NoPackageJsonAnswer {
+    kind: NoPackageJsonCase;
+    message: string;
+}
 /**
  * What `init` should say when there is no package.json.
  *
@@ -42,3 +58,10 @@ export declare function detectNonJsEcosystem(exists: (file: string) => boolean):
  * second needs to know that no path exists and why.
  */
 export declare function noPackageJsonMessage(exists: (file: string) => boolean, rootFiles?: readonly string[]): string;
+/**
+ * {@link noPackageJsonMessage}, plus which case it picked.
+ *
+ * `init` acts on the case (it writes nothing for {@link NoPackageJsonCase.WRONG_DIRECTORY}), so the
+ * choice is made here once rather than re-derived beside the message and kept in sync by hand.
+ */
+export declare function noPackageJsonAnswer(exists: (file: string) => boolean, rootFiles?: readonly string[]): NoPackageJsonAnswer;

package/dist/detect/non-js-project.js

@@ -97,6 +97,17 @@ export function detectNonJsEcosystem(exists) {
     }
     return undefined;
 }
+/** Which answer `init` gives when there is no package.json. */
+export const NoPackageJsonCase = {
+    /** No ecosystem marker and no page: the only honest answer is "run `init` somewhere else". */
+    WRONG_DIRECTORY: 'wrong_directory',
+    /** A page with no build step, which takes the script-tag snippet. */
+    STATIC_PAGE: 'static_page',
+    /** Flutter web paints into a canvas, so there is nothing to instrument. */
+    FLUTTER: 'flutter',
+    /** A recognised non-JS ecosystem, which can load the SDK from a URL. */
+    NON_JS: 'non_js',
+};
 /**
  * What `init` should say when there is no package.json.
  *
@@ -105,38 +116,59 @@ export function detectNonJsEcosystem(exists) {
  * second needs to know that no path exists and why.
  */
 export function noPackageJsonMessage(exists, rootFiles = []) {
+    return noPackageJsonAnswer(exists, rootFiles).message;
+}
+/**
+ * {@link noPackageJsonMessage}, plus which case it picked.
+ *
+ * `init` acts on the case (it writes nothing for {@link NoPackageJsonCase.WRONG_DIRECTORY}), so the
+ * choice is made here once rather than re-derived beside the message and kept in sync by hand.
+ */
+export function noPackageJsonAnswer(exists, rootFiles = []) {
     const ecosystem = detectNonJsEcosystem(exists);
     if (ecosystem === undefined) {
         if (exists('index.html') || rootFiles.some((name) => name.endsWith('.html'))) {
-            return ('This is a static page with no build step, so there is nothing for `reticle init` to wire. ' +
-                'Add the script-tag snippet below to the page while you develop, then reload it. Remove the ' +
-                'snippet before publishing: a static file has no development build to keep it out of production.');
+            return {
+                kind: NoPackageJsonCase.STATIC_PAGE,
+                message: 'This is a static page with no build step, so there is nothing for `reticle init` to wire. ' +
+                    'Add the script-tag snippet below to the page while you develop, then reload it. Remove the ' +
+                    'snippet before publishing: a static file has no development build to keep it out of production.',
+            };
         }
-        return ('No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
-            "your app's directory, or from a repo root that contains it.");
+        return {
+            kind: NoPackageJsonCase.WRONG_DIRECTORY,
+            message: 'No package.json found here, and no app directory beneath it either. Run `reticle init` from ' +
+                "your app's directory, or from a repo root that contains it.",
+        };
     }
     if (ecosystem === FLUTTER) {
         // An agent on a Flutter workspace asked us to "support Flutter, or clearly identify it as
         // unsupported during init". The second is the truthful one, and saying it by name in one line
         // is the difference between an agent that stops and an agent that spends an hour looking for
         // the package.json we told it was missing.
-        return ('This is a Flutter project. Reticle cannot instrument it, and no directory or flag will ' +
-            'change that: Reticle reads the DOM of a running page, and Flutter web paints its entire UI ' +
-            'into a single canvas element with no DOM behind it. Nothing here is missing or misconfigured. ' +
-            'If this repo also contains an ordinary web app with its own package.json, run `reticle init` ' +
-            'inside that directory instead.');
+        return {
+            kind: NoPackageJsonCase.FLUTTER,
+            message: 'This is a Flutter project. Reticle cannot instrument it, and no directory or flag will ' +
+                'change that: Reticle reads the DOM of a running page, and Flutter web paints its entire UI ' +
+                'into a single canvas element with no DOM behind it. Nothing here is missing or misconfigured. ' +
+                'If this repo also contains an ordinary web app with its own package.json, run `reticle init` ' +
+                'inside that directory instead.',
+        };
     }
-    return (`This looks like a ${ecosystem} project, and there is no package.json here or in any app ` +
-        'directory beneath it. That is not a blocker: Reticle needs its SDK loaded by the page, not ' +
-        'built by npm, and a page with no build step can load it from a URL. ' +
-        // The old message ended at "there is no directory you could run this from that would change
-        // that", which read as a refusal and was acted on as one — agents went looking for a bundler,
-        // or for a standalone build to inject by hand, or gave up and used a different tool. The
-        // capability was there the whole time; only the sentence was missing. Proven end to end on a
-        // page served by `python3 -m http.server` before this line was written.
-        'Add the script-tag snippet below to a template you only serve in development, then reload the ' +
-        'page. ' +
-        'If this project ALSO has a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
-        'its own package.json), running `reticle init` there instead gives you source mapping and ' +
-        'framework state as well: point at it with `--app <dir>`.');
+    return {
+        kind: NoPackageJsonCase.NON_JS,
+        message: `This looks like a ${ecosystem} project, and there is no package.json here or in any app ` +
+            'directory beneath it. That is not a blocker: Reticle needs its SDK loaded by the page, not ' +
+            'built by npm, and a page with no build step can load it from a URL. ' +
+            // The old message ended at "there is no directory you could run this from that would change
+            // that", which read as a refusal and was acted on as one — agents went looking for a bundler,
+            // or for a standalone build to inject by hand, or gave up and used a different tool. The
+            // capability was there the whole time; only the sentence was missing. Proven end to end on a
+            // page served by `python3 -m http.server` before this line was written.
+            'Add the script-tag snippet below to a template you only serve in development, then reload the ' +
+            'page. ' +
+            'If this project ALSO has a JS front end (a `frontend/`, `client/` or `assets/` directory with ' +
+            'its own package.json), running `reticle init` there instead gives you source mapping and ' +
+            'framework state as well: point at it with `--app <dir>`.',
+    };
 }

package/dist/detect/workspace-apps.d.ts

@@ -26,6 +26,11 @@ export declare function workspaceParents(sources: WorkspaceSources): string[];
  */
 /** Deps that mark a directory as a runnable web app even when it has no bundler config file. */
 export declare const APP_DEPS: readonly ["next", "vite", "electron-vite"];
+/**
+ * Whether `dir` is itself an app with a page: what the daemon asks before wiring a folder unasked,
+ * so a library or API package it happens to run in is left alone.
+ */
+export declare function isWebApp(dir: string, io: Pick<InitIo, 'exists' | 'readFile'>): boolean;
 /**
  * App directories under a workspace root.
  *
@@ -35,6 +40,15 @@ export declare const APP_DEPS: readonly ["next", "vite", "electron-vite"];
  * it knows it is in a workspace; this is the matching walk DOWN.
  */
 export declare function findWorkspaceApps(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
+/**
+ * Apps anywhere below a folder that is not one, for `init` run above its app with no workspace to
+ * say where the app is: a backend + frontend repo, a home folder, a docs site in `site/`.
+ *
+ * Breadth first and bounded (depth and folders read), never into dependencies, build output or
+ * hidden folders, and never below an app it found. Apps with a page win; a bare `index.html` with
+ * no package.json counts only when there is none, as the static page it is.
+ */
+export declare function findAppsBelow(io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 /**
  * Every package directory the workspace declares or holds, app-shaped or not.
  *
@@ -56,4 +70,6 @@ export declare function workspacePackageDirs(io: Pick<InitIo, 'readFile' | 'list
  * config into a stranger's root.
  */
 export declare function enclosingWorkspaceRoot(cwd: string, io: Pick<InitIo, 'readFile'>): string | undefined;
+/** The apps of the workspace at `root`, read through an io standing somewhere else in it. */
+export declare function appsAt(root: string, io: Pick<InitIo, 'exists' | 'readFile' | 'listDirs'>): string[];
 export {};

package/dist/detect/workspace-apps.js

@@ -179,6 +179,13 @@ function appSignal(dir, io) {
     // backend. A package with a dev script and no page is only a candidate when nothing else is.
     return hasPage(dir, pkgRaw, io) ? AppSignal.UI : AppSignal.SERVED;
 }
+/**
+ * Whether `dir` is itself an app with a page: what the daemon asks before wiring a folder unasked,
+ * so a library or API package it happens to run in is left alone.
+ */
+export function isWebApp(dir, io) {
+    return AppSignal.UI === appSignal(dir, io);
+}
 /**
  * App directories under a workspace root.
  *
@@ -230,6 +237,61 @@ export function findWorkspaceApps(io) {
     // app is exactly that — so it is demoted, never dropped.
     return [...new Set(found.length > 0 ? found : served)];
 }
+/** Folders the search for an app never enters: dependencies, output, and a home folder's own. */
+const NEVER_SEARCHED = new Set([
+    ...NEVER_A_PACKAGE,
+    'vendor',
+    'venv',
+    '__pycache__',
+    'Library',
+    'Applications',
+    'AppData',
+    'Pictures',
+    'Music',
+    'Movies',
+]);
+/** How deep the search goes: `client/web/app` is three, and nothing real is deeper than four. */
+const SEARCH_DEPTH = 4;
+/** Folders read before the search gives up, so a home folder costs a fraction of a second. */
+const SEARCH_BUDGET = 600;
+/**
+ * Apps anywhere below a folder that is not one, for `init` run above its app with no workspace to
+ * say where the app is: a backend + frontend repo, a home folder, a docs site in `site/`.
+ *
+ * Breadth first and bounded (depth and folders read), never into dependencies, build output or
+ * hidden folders, and never below an app it found. Apps with a page win; a bare `index.html` with
+ * no package.json counts only when there is none, as the static page it is.
+ */
+export function findAppsBelow(io) {
+    const apps = [];
+    const pages = [];
+    let level = io.listDirs('.').filter(searchable);
+    let read = 0;
+    for (let depth = 1; depth <= SEARCH_DEPTH && level.length > 0 && read < SEARCH_BUDGET; depth++) {
+        const next = [];
+        for (const dir of level) {
+            if (++read > SEARCH_BUDGET)
+                break;
+            if (AppSignal.UI === appSignal(dir, io)) {
+                apps.push(dir);
+                continue;
+            }
+            if (!io.exists(`${dir}/${PACKAGE_JSON}`) && io.exists(`${dir}/index.html`)) {
+                pages.push(dir);
+                continue;
+            }
+            next.push(...io
+                .listDirs(dir)
+                .filter(searchable)
+                .map((name) => `${dir}/${name}`));
+        }
+        level = next;
+    }
+    return apps.length > 0 ? apps : pages;
+}
+function searchable(name) {
+    return !name.startsWith('.') && !NEVER_SEARCHED.has(name);
+}
 /**
  * Every package directory the workspace declares or holds, app-shaped or not.
  *
@@ -283,3 +345,11 @@ export function enclosingWorkspaceRoot(cwd, io) {
     }
     return undefined;
 }
+/** The apps of the workspace at `root`, read through an io standing somewhere else in it. */
+export function appsAt(root, io) {
+    return findWorkspaceApps({
+        exists: (p) => io.exists(join(root, p)),
+        readFile: (p) => io.readFile(join(root, p)),
+        listDirs: (p) => io.listDirs(join(root, p)),
+    });
+}

package/dist/detect/workspace-redirect.d.ts

@@ -11,6 +11,18 @@
 import type { InitIo, InitOptions, InitResult } from '../run-types.js';
 /** Re-enter `init`, scoped to one directory of the workspace. */
 type RunInit = (options: InitOptions, io: InitIo) => InitResult;
+declare const POWERSHELL_ONLY_LABEL: "PowerShell only:";
+interface DisplayedWorkspaceAppCommand {
+    command: string;
+    label?: typeof POWERSHELL_ONLY_LABEL;
+}
+/**
+ * Render one discovered workspace app as a command the user can paste back into a shell.
+ *
+ * Plain paths need no quoting. Complex Windows paths are explicitly PowerShell-only because
+ * cmd.exe and PowerShell use different quoting grammars.
+ */
+export declare function displayedWorkspaceAppCommand(app: string, platform: NodeJS.Platform): DisplayedWorkspaceAppCommand;
 /**
  * When the current directory is a workspace root with no app of its own, wire the app instead of the
  * root. One candidate is wired silently (there is nothing to ask about); several are listed, because

package/dist/detect/workspace-redirect.js

@@ -11,7 +11,7 @@
 import { join } from 'node:path';
 import { detect, Framework } from './detect.js';
 import { detectNonJsEcosystem, noPackageJsonMessage } from './non-js-project.js';
-import { findWorkspaceApps, PACKAGE_JSON, workspacePackageDirs } from './workspace-apps.js';
+import { findAppsBelow, findWorkspaceApps, PACKAGE_JSON, workspacePackageDirs, } from './workspace-apps.js';
 import { projectIdOf, RETICLE_CONFIG_FILE } from './existing-config.js';
 import { chooseWorkspaceApp, withoutTrailingSlashes } from './declared/app-choice.js';
 const ROOT_CONFIG_LEAD = `This root's ${RETICLE_CONFIG_FILE} names`;
@@ -29,7 +29,57 @@ function appNamedByRootConfig(io) {
     const named = workspacePackageDirs(io).filter((dir) => projectIdOf(io.readFile(`${dir}/${RETICLE_CONFIG_FILE}`)) === wanted);
     return 1 === named.length ? named[0] : undefined;
 }
-const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` inside the one you want:';
+const AMBIGUOUS_HEADER = 'Several apps found in this workspace. Re-run `reticle init` for the one you want:';
+const BELOW_HEADER = 'No app in this folder. Several below it; re-run `reticle init` for the one you want:';
+const HOME_HEADER = 'This is your home folder, so init wires nothing on its own here. Apps found below it; run one:';
+const STATIC_PAGE = 'index.html';
+/** The folder `init` was run in is the person's home: a place to find apps, never to wire one. */
+function inHome(io) {
+    const trim = (p) => withoutTrailingSlashes(p.replace(/\\/g, '/'));
+    return trim(io.cwd()) === trim(io.homeDir());
+}
+/** Print the candidates as commands to paste, and stop: the choice is the person's. */
+function listApps(io, header, apps) {
+    io.print(header);
+    for (const a of apps) {
+        const displayed = displayedWorkspaceAppCommand(a, process.platform);
+        if (displayed.label !== undefined)
+            io.print(`  ${displayed.label}`);
+        io.print(`  ${displayed.command}`);
+    }
+    return { ok: false, applied: 0, manual: apps.length, listedAppsBelow: true };
+}
+const WORKSPACE_APP_COMMAND = 'reticle init --app';
+const ALREADY_WIRED = 'Already wired here:';
+const WIRE_ANOTHER = 'To wire another app:';
+const POWERSHELL_ONLY_LABEL = 'PowerShell only:';
+const PLAIN_SHELL_ARG = /^[A-Za-z0-9_./-]+$/;
+function posixShellArg(arg) {
+    return `'${arg.replaceAll("'", "'\"'\"'")}'`;
+}
+function powerShellArg(arg) {
+    return `'${arg.replaceAll("'", "''")}'`;
+}
+/**
+ * Render one discovered workspace app as a command the user can paste back into a shell.
+ *
+ * Plain paths need no quoting. Complex Windows paths are explicitly PowerShell-only because
+ * cmd.exe and PowerShell use different quoting grammars.
+ */
+export function displayedWorkspaceAppCommand(app, platform) {
+    if (PLAIN_SHELL_ARG.test(app)) {
+        return { command: `${WORKSPACE_APP_COMMAND} ${app}` };
+    }
+    if ('win32' === platform) {
+        return {
+            label: POWERSHELL_ONLY_LABEL,
+            command: `${WORKSPACE_APP_COMMAND} ${powerShellArg(app)}`,
+        };
+    }
+    return {
+        command: `${WORKSPACE_APP_COMMAND} ${posixShellArg(app)}`,
+    };
+}
 /**
  * When the current directory is a workspace root with no app of its own, wire the app instead of the
  * root. One candidate is wired silently (there is nothing to ask about); several are listed, because
@@ -59,7 +109,8 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
     const named = options.app === undefined || '' === options.app ? undefined : options.app;
     if (named !== undefined) {
         const wanted = withoutTrailingSlashes(named);
-        if (io.exists(`${wanted}/${PACKAGE_JSON}`))
+        // A plain page is an app too: `init` wires its index.html once it is standing in that folder.
+        if (io.exists(`${wanted}/${PACKAGE_JSON}`) || io.exists(`${wanted}/${STATIC_PAGE}`))
             return enterApp(options, io, wanted, 'Wiring', runInit);
         const inWanted = (file) => io.exists(`${wanted}/${file}`);
         io.print(detectNonJsEcosystem(inWanted) === undefined
@@ -84,16 +135,39 @@ export function redirectToWorkspaceApp(options, io, pkg, runInit) {
         io.print(chosen.message);
         return { ok: false, applied: 0, manual: 1 };
     }
+    // A home folder holds every project the person has; picking one for them is a guess.
+    if (chosen.app === undefined && inHome(io)) {
+        const found = 0 < apps.length ? apps : findAppsBelow(io);
+        return 0 < found.length ? listApps(io, HOME_HEADER, found) : null;
+    }
+    // No app one or two levels down and no manifest here: look deeper before giving up, so a repo
+    // whose web app sits at `client/web/app`, or a bare page in `site/`, is wired rather than refused.
+    if (0 === apps.length && !io.exists(PACKAGE_JSON) && chosen.app === undefined) {
+        const below = findAppsBelow(io);
+        if (1 === below.length && below[0] !== undefined)
+            return enterApp(options, io, below[0], 'No app in this directory — wiring', runInit);
+        if (1 < below.length)
+            return listApps(io, BELOW_HEADER, below);
+    }
     const target = chosen.app ?? (1 === apps.length ? apps[0] : undefined);
     if (target === undefined) {
         if (0 === apps.length)
             return null; // not a workspace — fall through to the normal HTML plan
-        io.print(AMBIGUOUS_HEADER);
-        for (const a of apps)
-            io.print(`  ${a}`);
-        io.print('');
-        io.print(`Or name one without changing directory:  reticle init --app ${apps[0] ?? '<dir>'}`);
-        return { ok: false, applied: 0, manual: apps.length };
+        // Apps already wired answer a re-run here: nothing to do at the root, which is pinned to none.
+        const wired = apps.filter((a) => io.exists(`${a}/${RETICLE_CONFIG_FILE}`));
+        io.print(0 === wired.length ? AMBIGUOUS_HEADER : `${ALREADY_WIRED} ${wired.join(', ')}.`);
+        const rest = apps.filter((a) => !wired.includes(a));
+        if (0 < wired.length && 0 < rest.length)
+            io.print(WIRE_ANOTHER);
+        for (const a of 0 === wired.length ? apps : rest) {
+            const displayed = displayedWorkspaceAppCommand(a, process.platform);
+            if (displayed.label !== undefined)
+                io.print(`  ${displayed.label}`);
+            io.print(`  ${displayed.command}`);
+        }
+        return 0 === wired.length
+            ? { ok: false, applied: 0, manual: apps.length }
+            : { ok: true, applied: 0, manual: 0 };
     }
     return enterApp(options, io, target, 'No app in this directory — wiring', runInit);
 }
@@ -115,5 +189,6 @@ function enterApp(options, io, target, lead, runInit) {
         // Where the human is STANDING, kept across the redirect: their agent session runs here, so
         // this is the only place a `/reticle` command file can be found by it.
         agentRoot: options.agentRoot ?? options.cwd,
+        severalApps: true === options.severalApps || 1 < findWorkspaceApps(io).length,
     }, io.scoped(target));
 }

package/dist/diagnose/closing-hint.d.ts

@@ -31,4 +31,10 @@ export declare const FEEDBACK_HINT: string;
  */
 export declare function restartHint(mcpStatus: StepStatus | undefined, 
 /** The project's own dev command, when package.json named one. */
-devCommand?: string): string;
+devCommand?: string, 
+/**
+ * Titles of other clients' registration steps this run left for the reader (the `⚠` rows). The
+ * Claude Code row says nothing about them, so without these the closing line contradicts the
+ * report above it.
+ */
+manualClients?: readonly string[]): string;