docugate 0.3.0 → 0.4.0

package/dist/api.d.ts

@@ -1,3 +1,5 @@
+/** The tool running the CLI, from what it sets in the environment. */
+export declare function detectAgent(env?: NodeJS.ProcessEnv): string;
 /** Module-level default, captured at import time (used by CLI commands). */
 export declare const BASE_URL: string;
 export declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;

package/dist/api.js

@@ -1,4 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { loadCredentials, saveCredentials } from './auth.js';
+const CLI_VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '';
+    }
+    catch {
+        return '';
+    }
+})();
+/** The tool running the CLI, from what it sets in the environment. */
+export function detectAgent(env = process.env) {
+    if (env.CLAUDECODE)
+        return 'Claude Code';
+    if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT)
+        return 'Cursor';
+    if (env.GITHUB_COPILOT_CLI || env.COPILOT_AGENT)
+        return 'Copilot';
+    if (env.CI)
+        return 'CI';
+    return 'Terminal';
+}
 /** Module-level default, captured at import time (used by CLI commands). */
 export const BASE_URL = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
 const ERROR_MESSAGES = {
@@ -24,6 +46,11 @@ export async function apiFetch(path, init = {}) {
     };
     if (creds) {
         headers['Authorization'] = `Bearer ${creds.token}`;
+        // What the dashboard's Agents screen lists: this folder's name and the tool
+        // running the CLI. No paths, no file contents.
+        headers['x-docugate-project'] = basename(process.cwd());
+        headers['x-docugate-agent'] = detectAgent();
+        headers['x-docugate-version'] = CLI_VERSION;
     }
     // Re-read the env at call time so tests that set DOCUGATE_URL after import work.
     const base = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';

package/dist/banner.d.ts

@@ -1,5 +1,5 @@
 export declare const TAGLINE = "Tours and docs for your codebase";
-/** The wordmark as five plain lines, no color. */
+/** The wordmark as two plain lines, no color. */
 export declare function wordmark(text?: string, gap?: number): string[];
 export declare function packageVersion(): string;
 export type BannerOptions = {

package/dist/banner.js

@@ -1,43 +1,36 @@
 import { readFileSync } from 'node:fs';
-import { colorDepth, fg, logoBanner } from './logo.js';
+import { colorDepth, fg } from './logo.js';
 import { colorOn, isMintty } from './ui.js';
-// The banner: DOCUGATE in block letters, shaded from cream to gold like the
-// owl, with the tagline and version under it. It adapts to where it is drawn:
-// beside the owl in a wide terminal, alone in a normal one, as a single line
-// in a narrow one, and without color when color is off. It is only ever
-// printed to a real terminal, so logs and CI never see it.
+// The banner: DOCUGATE in a compact two-row block font, cream over gold
+// like the owl, with the version beside it. Small on purpose: it sits above
+// the menu, and the menu is what the person came for. A narrow terminal gets
+// one line, and without color it is plain text. It is only ever printed to a
+// person at a terminal, so logs and CI never see it.
 export const TAGLINE = 'Tours and docs for your codebase';
-const SITE = 'https://www.trydocugate.site';
-// A five-row block font, just the letters in the name. Every glyph is five
-// columns wide, so the wordmark's width is simply letters * 5 + gaps.
+// Two rows per letter, three columns wide, drawn with half blocks.
 const GLYPHS = {
-    D: ['████ ', '█   █', '█   █', '█   █', '████ '],
-    O: [' ███ ', '█   █', '█   █', '█   █', ' ███ '],
-    C: [' ████', '█    ', '█    ', '█    ', ' ████'],
-    U: ['█   █', '█   █', '█   █', '█   █', ' ███ '],
-    G: [' ████', '█    ', '█  ██', '█   █', ' ████'],
-    A: [' ███ ', '█   █', '█████', '█   █', '█   █'],
-    T: ['█████', '  █  ', '  █  ', '  █  ', '  █  '],
-    E: ['█████', '█    ', '████ ', '█    ', '█████'],
+    D: ['█▀▄', '█▄▀'],
+    O: ['█▀█', '█▄█'],
+    C: ['█▀▀', '█▄▄'],
+    U: ['█ █', '█▄█'],
+    G: ['█▀▀', '█▄█'],
+    A: ['▄▀█', '█▀█'],
+    T: ['▀█▀', ' █ '],
+    E: ['█▀▀', '██▄'],
 };
-// Cream at the top, through gold, to deep gold at the bottom.
+// Cream on the top row, gold on the bottom.
 const SHADES = [
     [245, 240, 227],
-    [246, 222, 150],
     [244, 196, 63],
-    [230, 175, 46],
-    [217, 154, 30],
 ];
 /** Narrower than this and the wordmark would wrap, so one line is shown. */
-const WORDMARK_MIN_COLUMNS = 60;
-/** Wide enough for the owl beside the wordmark. */
-const OWL_MIN_COLUMNS = 96;
-/** The wordmark as five plain lines, no color. */
-export function wordmark(text = 'DOCUGATE', gap = 2) {
+const WORDMARK_MIN_COLUMNS = 40;
+/** The wordmark as two plain lines, no color. */
+export function wordmark(text = 'DOCUGATE', gap = 1) {
     const letters = [...text.toUpperCase()].map((c) => GLYPHS[c]);
     if (letters.some((g) => !g))
         throw new Error(`The banner font has no glyph for every letter of "${text}".`);
-    return [0, 1, 2, 3, 4].map((row) => letters.map((g) => g[row]).join(' '.repeat(gap)).trimEnd());
+    return [0, 1].map((row) => letters.map((g) => g[row]).join(' '.repeat(gap)).trimEnd());
 }
 export function packageVersion() {
     const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -48,15 +41,10 @@ export function banner(options = {}) {
     const { 
     // mintty reports no width to a piped console; COLUMNS, or a usual window, stands in.
     columns = process.stdout.columns ?? (Number(process.env.COLUMNS) || (isMintty() ? 100 : 0)), color = colorOn(), version = packageVersion(), env = process.env, } = options;
-    const dim = (t) => (color ? `\x1b[2m${t}\x1b[0m` : t);
-    if (columns < WORDMARK_MIN_COLUMNS) {
-        const full = `  DocuGate · ${TAGLINE} · v${version}`;
-        return ['', full.length <= columns ? full : `  DocuGate v${version}`, ''];
-    }
+    const dim = (t) => (color ? `${t}` : t);
+    if (columns < WORDMARK_MIN_COLUMNS)
+        return ['', `  DocuGate ${dim(`v${version}`)}`, ''];
     const depth = colorDepth(env);
-    const art = wordmark().map((line, row) => (color ? `${fg(SHADES[row], depth)}${line}\x1b[0m` : line));
-    const text = [...art, '', dim(TAGLINE), dim(`v${version} · ${SITE}`)];
-    if (color && columns >= OWL_MIN_COLUMNS)
-        return logoBanner(text, env);
-    return ['', ...text.map((t) => (t ? `  ${t}` : '')), ''];
+    const [top, bottom] = wordmark().map((line, row) => (color ? `${fg(SHADES[row], depth)}${line}` : line));
+    return ['', `  ${top}`, `  ${bottom}  ${dim(`v${version}`)}`, ''];
 }

package/dist/cli.js

@@ -4,6 +4,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs, UsageError } from './args.js';
+import { auditCommand, connectCommand } from './project.js';
 import { banner, packageVersion } from './banner.js';
 import { check } from './check.js';
 import { COMMANDS, findCommand, renderCommandHelp, renderCompletion, renderGroupHelp, renderHelp } from './commands.js';
@@ -210,6 +211,21 @@ async function run(argv) {
             console.log(session.user ? `@${session.user.githubLogin}` : `Not signed in. Run ${hint('login')}.`);
             return;
         }
+        case 'connect': {
+            process.exitCode = await connectCommand(root, {
+                space: one('space'),
+                frequency: one('frequency'),
+                type: one('type'),
+                backendDir: one('backend-dir'),
+                noAudit: args.bools.has('no-audit'),
+                yes: args.bools.has('yes') || noInput,
+            });
+            return;
+        }
+        case 'audit': {
+            process.exitCode = await auditCommand(root, { failOn: one('fail-on'), json: args.bools.has('json') });
+            return;
+        }
         case 'developers': {
             if (noInput && !args.bools.has('yes'))
                 fail('developers asks questions. Run it in a terminal, or add --yes to take every default.');

package/dist/commands.js

@@ -163,6 +163,36 @@ export const COMMANDS = [
         examples: ['docugate logout'],
         account: 'none',
     },
+    {
+        name: 'connect',
+        group: 'Account',
+        summary: 'Connect this project to your account, to run it from the dashboard',
+        description: 'Links this repository to your DocuGate account. Then the dashboard decides which documentation it updates, how often, and what kind of project it is. ' +
+            'It shares the repository name, the tool running the CLI, the outcome of each sync, and the names and versions of public packages in your lockfiles. Never your code.',
+        flags: [
+            { name: 'space', value: 'slug', description: 'The space this project updates' },
+            { name: 'frequency', value: 'when', description: 'How often docs are checked: push, daily, weekly or off' },
+            { name: 'type', value: 'kind', description: 'frontend, backend, serverless or monorepo (default: detected)' },
+            { name: 'backend-dir', value: 'folder', description: 'In a monorepo, the folder that holds the backend' },
+            { name: 'no-audit', description: 'Do not send package names to check for vulnerabilities' },
+            YES,
+        ],
+        examples: ['docugate connect', 'docugate connect --space handbook --frequency daily --type monorepo --backend-dir apps/api --yes'],
+        account: 'required',
+    },
+    {
+        name: 'audit',
+        group: 'Checks',
+        summary: 'Check this project’s packages for known vulnerabilities',
+        description: 'Reads your lockfiles without installing or running anything, and checks public packages against the OSV.dev vulnerability database. ' +
+            'Private packages stay on your machine. It only warns, unless you ask it to fail with --fail-on.',
+        flags: [
+            { name: 'fail-on', value: 'severity', description: 'Exit 1 at this severity or above: critical, high, moderate or low' },
+            { name: 'json', description: 'Print the result as JSON' },
+        ],
+        examples: ['docugate audit', 'docugate audit --fail-on high'],
+        account: 'required',
+    },
     {
         name: 'whoami',
         group: 'Account',

package/dist/init.d.ts

@@ -19,6 +19,7 @@ export declare function init(root: string, opts?: {
     dir?: string;
     title?: string;
 }): InitResult;
+export declare const AGENTS_FILE = "AGENTS.md";
 export type Role = 'frontend' | 'backend' | 'both';
 /** Minimal I/O surface so the flow can be driven by tests without a terminal. */
 export interface IO {

package/dist/init.js

@@ -38,12 +38,76 @@ export function init(root, opts = {}) {
     else {
         mkdirSync(base, { recursive: true });
         writeFileSync(join(base, 'index.md'), `# ${title}\n\nWelcome. This page is the landing page of your DocuGate space.\n\n` +
+            `New here? Read [Start here](start-here.md) first.\n\n` +
             `Every \`.md\` file in \`${docsDir}/\` becomes a page, and every folder becomes a\n` +
             `section in the sidebar. The first \`# heading\` in a file is its title.\n`);
         created.push(`${docsDir}/index.md`);
+        writeFileSync(join(base, 'start-here.md'), startHere(title));
+        created.push(`${docsDir}/start-here.md`);
+    }
+    // For the AI tools that work in this repository: where the docs are, and how
+    // they are written. Never touched if the repository already has one.
+    if (existsSync(join(root, AGENTS_FILE))) {
+        kept.push(AGENTS_FILE);
+    }
+    else {
+        writeFileSync(join(root, AGENTS_FILE), agentsGuide(title, docsDir));
+        created.push(AGENTS_FILE);
     }
     return { created, kept, docsDir };
 }
+export const AGENTS_FILE = 'AGENTS.md';
+/** The page a new reader opens first: what is here, and how to find the rest. */
+function startHere(title) {
+    return `# Start here
+
+This is the documentation for ${title}. Five minutes here saves an hour later.
+
+## What is in these docs
+
+- **Guides** walk through one task from start to finish.
+- **Reference** pages list every option, for looking things up.
+- **Runbooks** say what to do when something breaks.
+
+Replace this list with the sections your docs actually have.
+
+## Finding things
+
+- Press \`/\` to search every page.
+- The sidebar follows the folders in the repository, so a page lives where you
+  would look for it.
+
+## Getting help
+
+Say where to ask questions: a channel, an email address, or a person.
+`;
+}
+/** AGENTS.md: what an AI coding tool should know before it writes docs here. */
+function agentsGuide(title, docsDir) {
+    return `# AGENTS.md
+
+Guidance for AI coding tools working in ${title}.
+
+## Documentation
+
+- The docs live in \`${docsDir}/\` and are published with DocuGate. Every push
+  updates the site; there is no build step.
+- Every \`.md\` file is a page and every folder is a sidebar section. The first
+  \`# heading\` in a file is its title.
+- \`${docsDir}/index.md\` is the landing page. \`${docsDir}/start-here.md\` is the
+  first page a new reader opens.
+- When you change behaviour, update the page that describes it in the same
+  change. Prefer editing an existing page to adding a new one.
+- Run \`docugate check\` before committing: it confirms every page parses and
+  every link resolves.
+
+## Writing style
+
+- Short sentences, plain words, one idea per paragraph.
+- Name commands, files and settings exactly, in backticks.
+- Lead with the task the reader came to do, then the details.
+`;
+}
 export function makeDefaultIO() {
     const isTTY = Boolean(process.stdin.isTTY);
     return {

package/dist/lockfiles.d.ts

@@ -0,0 +1,24 @@
+export type Dependency = {
+    ecosystem: 'npm' | 'PyPI' | 'Go';
+    name: string;
+    version: string;
+    /** Listed by the project itself. Null when the lockfile cannot say. */
+    direct?: boolean | null;
+    /** For an indirect package, the direct one that brings it in, when known. */
+    via?: string | null;
+    lockfile?: string;
+};
+export type LockfileScan = {
+    dependencies: Dependency[];
+    files: string[];
+    unchecked: string[];
+};
+type Parser = (text: string, ownOwner?: string) => Dependency[];
+export declare const parsePackageLock: Parser;
+export declare const parsePnpmLock: Parser;
+export declare const parseYarnLock: Parser;
+export declare const parseRequirements: Parser;
+export declare const parseGoMod: Parser;
+/** Every lockfile in the project, monorepo folders included, within a depth limit. */
+export declare function scanLockfiles(root: string, ownOwner?: string): LockfileScan;
+export {};

package/dist/lockfiles.js

@@ -0,0 +1,203 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const PUBLIC_NPM = /^https:\/\/registry\.(npmjs\.org|yarnpkg\.com)\//;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', '.next', '.venv', 'venv', '__pycache__', 'target', 'coverage']);
+const MAX_DEPTH = 4;
+const MAX_DIRS = 2000;
+export const parsePackageLock = (text) => {
+    const lock = JSON.parse(text);
+    const out = [];
+    if (lock.packages) {
+        for (const [path, entry] of Object.entries(lock.packages)) {
+            const at = path.lastIndexOf('node_modules/');
+            if (at < 0 || entry.link || !entry.version || !entry.resolved || !PUBLIC_NPM.test(entry.resolved))
+                continue;
+            out.push({ ecosystem: 'npm', name: path.slice(at + 'node_modules/'.length), version: entry.version });
+        }
+        addViaFromLock(lock.packages, out);
+    }
+    else if (lock.dependencies) {
+        collectV1(lock.dependencies, out);
+    }
+    else {
+        throw new Error('no packages listed');
+    }
+    return out;
+};
+/** Walks down from each direct package, so an indirect one can name who brought it in. */
+function addViaFromLock(packages, out) {
+    const root = packages[''];
+    const direct = Object.keys({ ...root?.dependencies, ...root?.devDependencies });
+    const via = new Map();
+    for (const top of direct) {
+        const queue = [top];
+        const seen = new Set(queue);
+        while (queue.length) {
+            const name = queue.shift();
+            for (const child of Object.keys(packages[`node_modules/${name}`]?.dependencies ?? {})) {
+                if (seen.has(child))
+                    continue;
+                seen.add(child);
+                if (!via.has(child) && !direct.includes(child))
+                    via.set(child, top);
+                queue.push(child);
+            }
+        }
+    }
+    for (const dep of out)
+        if (via.has(dep.name))
+            dep.via = via.get(dep.name);
+}
+function collectV1(deps, out) {
+    for (const [name, entry] of Object.entries(deps)) {
+        if (entry.version && entry.resolved && PUBLIC_NPM.test(entry.resolved))
+            out.push({ ecosystem: 'npm', name, version: entry.version });
+        if (entry.dependencies)
+            collectV1(entry.dependencies, out);
+    }
+}
+export const parsePnpmLock = (text) => {
+    const out = [];
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^packages:\s*$/.test(l));
+    if (start < 0)
+        throw new Error('no packages section');
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\S/.test(line))
+            break;
+        const key = line.match(/^ {2}'?\/?((?:@[^/]+\/)?[^@/\s']+)[@/](\d[^:(\s']*)[^:]*'?:/);
+        if (!key)
+            continue;
+        // The next line says where it came from. A tarball means not the registry.
+        if (/tarball:|type: git|directory:/.test(lines[i + 1] ?? ''))
+            continue;
+        out.push({ ecosystem: 'npm', name: key[1], version: key[2] });
+    }
+    return out;
+};
+export const parseYarnLock = (text) => {
+    const out = [];
+    for (const block of text.split(/\r?\n\r?\n/)) {
+        const head = block.split(/\r?\n/).find((l) => /^\S.*:\s*$/.test(l) && !l.startsWith('#') && !l.startsWith('__metadata'));
+        if (!head)
+            continue;
+        const name = head.replace(/^"/, '').match(/^(@?[^@]+)@/)?.[1];
+        const version = block.match(/^\s+version:?\s+"?([^"\s]+)"?/m)?.[1];
+        if (!name || !version)
+            continue;
+        const resolved = block.match(/^\s+resolved\s+"([^"]+)"/m)?.[1];
+        const berry = block.match(/^\s+resolution:\s+"[^"]*@(npm):/m);
+        if (resolved ? !PUBLIC_NPM.test(resolved) : !berry)
+            continue;
+        out.push({ ecosystem: 'npm', name, version });
+    }
+    return out;
+};
+export const parseRequirements = (text) => {
+    // A custom index means these names may be private, so none of them leave.
+    if (/^\s*(--index-url|-i\s|--extra-index-url|--find-links)/m.test(text))
+        throw new Error('uses a custom package index');
+    const out = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const m = raw.split('#')[0].trim().match(/^([A-Za-z0-9][\w.-]*)(?:\[[^\]]*\])?\s*==\s*([\w.!+-]+)/);
+        if (m)
+            out.push({ ecosystem: 'PyPI', name: m[1], version: m[2], direct: true });
+    }
+    return out;
+};
+export const parseGoMod = (text, ownOwner) => {
+    const out = [];
+    const replaced = new Set([...text.matchAll(/^\s*(?:replace\s+)?(\S+)(?:\s+v\S+)?\s+=>/gm)].map((m) => m[1]));
+    const add = (mod, version, direct) => {
+        if (replaced.has(mod))
+            return;
+        // Modules of the same GitHub account are as likely private as not.
+        if (ownOwner && mod.toLowerCase().startsWith(`github.com/${ownOwner.toLowerCase()}/`))
+            return;
+        out.push({ ecosystem: 'Go', name: mod, version: version.replace(/^v/, ''), direct });
+    };
+    let inBlock = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.split('//')[0].trim();
+        if (/^require\s*\($/.test(line))
+            inBlock = true;
+        else if (line === ')')
+            inBlock = false;
+        else {
+            const m = inBlock ? line.match(/^(\S+)\s+(v\S+)$/) : line.match(/^require\s+(\S+)\s+(v\S+)$/);
+            if (m)
+                add(m[1], m[2], !/\/\/\s*indirect/.test(raw));
+        }
+    }
+    return out;
+};
+const PARSERS = {
+    'package-lock.json': parsePackageLock,
+    'pnpm-lock.yaml': parsePnpmLock,
+    'yarn.lock': parseYarnLock,
+    'requirements.txt': parseRequirements,
+    'go.mod': parseGoMod,
+};
+/**
+ * The packages this folder's package.json asks for. Null when it cannot say: none
+ * there, or a workspace root, whose real lists are in each package's own file.
+ */
+function directNames(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if (pkg.workspaces)
+            return null;
+        return new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies, ...pkg.optionalDependencies }));
+    }
+    catch {
+        return null;
+    }
+}
+/** Every lockfile in the project, monorepo folders included, within a depth limit. */
+export function scanLockfiles(root, ownOwner) {
+    const seen = new Map();
+    const files = [];
+    const unchecked = [];
+    let dirs = 0;
+    const visit = (dir, depth) => {
+        if (++dirs > MAX_DIRS)
+            return;
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(dir, name);
+            const parser = PARSERS[name];
+            if (parser) {
+                const shown = relative(root, path).replace(/\\/g, '/');
+                try {
+                    const own = directNames(dir);
+                    for (const dep of parser(readFileSync(path, 'utf8'), ownOwner)) {
+                        const direct = dep.direct ?? (dep.ecosystem === 'npm' && own ? own.has(dep.name) : null);
+                        seen.set(`${dep.ecosystem}:${dep.name}@${dep.version}`, { ...dep, direct, lockfile: shown });
+                    }
+                    files.push(shown);
+                }
+                catch {
+                    unchecked.push(shown);
+                }
+            }
+            else if (depth < MAX_DEPTH && !SKIP_DIRS.has(name) && !name.startsWith('.')) {
+                try {
+                    if (statSync(path).isDirectory())
+                        visit(path, depth + 1);
+                }
+                catch {
+                    // Gone or unreadable: not a lockfile we can speak for.
+                }
+            }
+        }
+    };
+    visit(root, 0);
+    return { dependencies: [...seen.values()], files, unchecked };
+}

package/dist/menu.d.ts

@@ -7,10 +7,23 @@ export type Action = string[];
 export declare function buildChoices(s: Status, now?: Date): Choice<Action>[];
 /** The line under the list: who you are, and the one thing worth doing. */
 export declare function menuNote(s: Status, now?: Date): string;
+/** Who is signed in: the one line the launch screen keeps above the list. */
+export declare function whoNote(s: Status): string;
+export type Section = 'main' | 'tours' | 'more';
+/**
+ * The launch menu, short enough to see at once: the few things people come
+ * for on the first screen, the rest one step away under Tours and More. A step
+ * that cannot run yet is left out rather than shown greyed, so every line is
+ * something to do. Labels and rules come from buildChoices, written once.
+ */
+export declare function buildMenu(s: Status, section: Section): Choice<Action>[];
 export type MenuDeps = {
     pick?: typeof select<Action>;
     /** For terminals that cannot do arrow keys: a numbered list instead. */
     numbered?: boolean;
 };
-/** Shows the menu and returns what was chosen, or null to quit. */
+/**
+ * Shows the menu and returns the command chosen, or null to quit. Tours and
+ * More open their own short list, with Back to return.
+ */
 export declare function runMenu(status: Status, deps?: MenuDeps): Promise<Action | null>;

package/dist/menu.js

@@ -130,26 +130,82 @@ export function menuNote(s, now = new Date()) {
     }
     return dim(bits.join(' · '));
 }
-/** Shows the menu and returns what was chosen, or null to quit. */
+/** Who is signed in: the one line the launch screen keeps above the list. */
+export function whoNote(s) {
+    if (s.account.state === 'signed-in')
+        return `signed in as ${gold(`@${s.account.login}`)}`;
+    return dim(s.account.state === 'offline' ? 'offline' : 'not signed in');
+}
+/** Values that move around the menu rather than run a command. */
+const GO = { tours: ['@tours'], more: ['@more'], back: ['@back'], quit: ['@quit'] };
+/**
+ * The launch menu, short enough to see at once: the few things people come
+ * for on the first screen, the rest one step away under Tours and More. A step
+ * that cannot run yet is left out rather than shown greyed, so every line is
+ * something to do. Labels and rules come from buildChoices, written once.
+ */
+export function buildMenu(s, section) {
+    const all = buildChoices(s);
+    const pick = (...commands) => commands
+        .map((command) => all.find((c) => c.value.join(' ') === command))
+        .filter((c) => Boolean(c && !c.disabled))
+        .map((c) => ({ ...c, status: undefined, recommended: c.recommended }));
+    if (section === 'tours') {
+        return [...pick('tour init', 'tour install', 'tour serve'), { value: [...GO.back], label: 'Back' }];
+    }
+    if (section === 'more') {
+        const hook = all.find((c) => c.value[0] === 'sync' && c.value[1] === 'hook');
+        return [
+            ...pick('sync --dry-run', 'sync init', ...(hook ? [hook.value.join(' ')] : []), 'status', 'openapi', 'help'),
+            { value: [...GO.back], label: 'Back' },
+        ];
+    }
+    const signedIn = s.account.state === 'signed-in';
+    return [
+        ...pick('developers', 'init', 'sync', 'check'),
+        { value: [...GO.tours], label: 'Tours' },
+        { value: [...GO.more], label: 'More' },
+        ...pick(signedIn ? 'logout' : 'login'),
+        { value: [...GO.quit], label: 'Quit' },
+    ];
+}
+/**
+ * Shows the menu and returns the command chosen, or null to quit. Tours and
+ * More open their own short list, with Back to return.
+ */
 export async function runMenu(status, deps = {}) {
-    const choices = buildChoices(status);
-    if (deps.numbered)
-        return numbered(choices, status);
     const pick = deps.pick ?? select;
-    return pick({ title: 'What next?', choices, note: menuNote(status), rows: 8 });
+    let section = 'main';
+    for (;;) {
+        const choices = buildMenu(status, section);
+        const note = section === 'main' ? whoNote(status) : dim(section === 'tours' ? 'Tours' : 'More');
+        const chosen = deps.numbered ? await numbered(choices, note) : await pick({ choices, note, minimal: true });
+        if (!chosen || chosen[0] === GO.quit[0])
+            return null;
+        if (chosen[0] === GO.back[0])
+            section = 'main';
+        else if (chosen[0] === GO.tours[0])
+            section = 'tours';
+        else if (chosen[0] === GO.more[0])
+            section = 'more';
+        else
+            return chosen;
+    }
 }
-async function numbered(choices, status) {
-    const usable = choices.filter((c) => !c.disabled);
-    console.log(`\n  ${bold('What next?')}  ${menuNote(status)}\n`);
-    usable.forEach((c, i) => console.log(`  ${gold(String(i + 1).padStart(2))}  ${c.label}${c.recommended ? gold('  ●') : ''}${c.status ? dim(`  ${c.status}`) : ''}`));
+async function numbered(choices, note) {
+    console.log(`
+  ${note}
+`);
+    choices.forEach((c, i) => console.log(`  ${dim(String(i + 1).padStart(2))}  ${c.label}`));
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const def = Math.max(0, usable.findIndex((c) => c.recommended)) + 1;
-        const answer = (await rl.question(`\n  Choose 1-${usable.length}, or q to quit ${dim(`[${def}]`)}: `)).trim().toLowerCase();
+        const def = Math.max(0, choices.findIndex((c) => c.recommended)) + 1;
+        const answer = (await rl.question(`
+  ${dim(`Choose 1-${choices.length} [${def}]`)}: `)).trim().toLowerCase();
         if (answer === 'q')
             return null;
         const n = answer === '' ? def : Number(answer);
-        return Number.isInteger(n) && usable[n - 1] ? usable[n - 1].value : null;
+        return Number.isInteger(n) && choices[n - 1] ? choices[n - 1].value : null;
     }
     finally {
         rl.close();