@agentrhq/webcmd 0.2.4 → 0.3.0

package/dist/src/hosted/setup.test.js

@@ -0,0 +1,68 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { getConfigPath } from './config.js';
+import { runHostedSetup } from './setup.js';
+let tempDir;
+afterEach(async () => {
+    if (tempDir)
+        await rm(tempDir, { recursive: true, force: true });
+    tempDir = undefined;
+});
+describe('webcmd setup', () => {
+    it('writes local mode from interactive answer', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-'));
+        const answers = ['local'];
+        const messages = [];
+        const env = { WEBCMD_CONFIG_DIR: tempDir };
+        const code = await runHostedSetup({
+            env,
+            now: () => new Date('2026-07-08T00:00:00.000Z'),
+            question: async () => answers.shift() ?? '',
+            write: (message) => messages.push(message),
+        });
+        expect(code).toBe(0);
+        expect(JSON.parse(await readFile(getConfigPath({ env }), 'utf8'))).toEqual({
+            mode: 'local',
+            updatedAt: '2026-07-08T00:00:00.000Z',
+        });
+        expect(messages.join('')).toContain('local mode');
+    });
+    it('writes hosted mode and validates with /v1/me', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-'));
+        const answers = ['hosted', 'wcmd_live_test'];
+        const env = { WEBCMD_CONFIG_DIR: tempDir };
+        const requests = [];
+        const prompts = [];
+        const code = await runHostedSetup({
+            env,
+            now: () => new Date('2026-07-08T00:00:00.000Z'),
+            question: async (prompt) => {
+                prompts.push(prompt);
+                return answers.shift() ?? '';
+            },
+            fetchImpl: async (url, init) => {
+                requests.push({
+                    url: String(url),
+                    authorization: new Headers(init?.headers).get('authorization'),
+                });
+                return new Response(JSON.stringify({ ok: true, user: { id: 'user_demo' } }), { status: 200 });
+            },
+            write: () => undefined,
+        });
+        expect(code).toBe(0);
+        expect(prompts).toEqual([
+            'Use hosted Webcmd Cloud or local Webcmd? [hosted/local] ',
+            'Webcmd API key: ',
+        ]);
+        expect(requests).toEqual([{ url: 'https://api.webcmd.dev/v1/me', authorization: 'Bearer wcmd_live_test' }]);
+        expect(JSON.parse(await readFile(getConfigPath({ env }), 'utf8'))).toMatchObject({
+            mode: 'hosted',
+            hosted: {
+                apiBaseUrl: 'https://api.webcmd.dev',
+                apiKey: 'wcmd_live_test',
+            },
+        });
+    });
+});

package/dist/src/hosted/types.d.ts

@@ -0,0 +1,97 @@
+export type HostedCommandStrategy = 'PUBLIC' | 'COOKIE' | 'INTERCEPT' | 'UI' | 'LOCAL' | string;
+export interface HostedCommandArg {
+    name: string;
+    type?: string;
+    required?: boolean;
+    valueRequired?: boolean;
+    positional?: boolean;
+    default?: unknown;
+    help?: string;
+    choices?: unknown[];
+}
+export interface HostedCommand {
+    site: string;
+    name: string;
+    aliases?: string[];
+    command: string;
+    description: string;
+    access: 'read' | 'write' | string;
+    strategy: HostedCommandStrategy;
+    browser: boolean;
+    args: HostedCommandArg[];
+    columns?: string[];
+    domain?: string | null;
+    defaultFormat?: string | null;
+}
+export interface HostedManifest {
+    userId: string;
+    generatedAt: string;
+    commands: HostedCommand[];
+}
+export interface HostedExecuteResponse {
+    ok: true;
+    result?: unknown;
+    data?: unknown;
+    rows?: unknown;
+    columns?: string[];
+    trace?: unknown;
+}
+export type HostedBrowserActionName = 'back' | 'click' | 'close-window' | 'console' | 'exec' | 'fill' | 'frames' | 'insert-text' | 'navigate' | 'network' | 'press-key' | 'screenshot' | 'scroll' | 'set-file-input' | 'snapshot' | 'tabs' | 'type' | 'wait';
+export interface HostedBrowserRunRequest {
+    command: string;
+    args: Record<string, unknown>;
+    profile?: string;
+    windowMode?: 'foreground' | 'background';
+    trace?: string;
+}
+export interface HostedBrowserRunResponse {
+    ok: true;
+    run: {
+        executionId: string;
+        session: string;
+        profile: {
+            id: string;
+            displayName: string;
+        };
+        liveViewUrl?: string;
+    };
+}
+export interface HostedBrowserActionRequest {
+    action: HostedBrowserActionName;
+    args: Record<string, unknown>;
+    profile?: string;
+}
+export interface HostedBrowserActionResponse {
+    ok: true;
+    result?: unknown;
+    columns?: string[];
+    trace?: unknown;
+}
+export interface HostedBrowserFinishRequest {
+    status: 'succeeded' | 'failed' | 'timed_out';
+    errorCode?: string;
+    profile?: string;
+}
+export interface HostedBrowserFinishResponse {
+    ok: true;
+    execution: {
+        id: string;
+        status: 'succeeded' | 'failed' | 'timed_out';
+    };
+}
+export interface HostedBrowserRunActionInput extends HostedBrowserRunRequest, HostedBrowserActionRequest {
+}
+export interface HostedBrowserRunActionResponse extends HostedBrowserActionResponse {
+    run: HostedBrowserRunResponse['run'];
+    execution: HostedBrowserFinishResponse['execution'];
+}
+export interface HostedErrorResponse {
+    ok: false;
+    error: {
+        code?: string;
+        message?: string;
+        help?: string;
+        hint?: string;
+        exitCode?: number;
+    };
+}

package/dist/src/hosted/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/main.js

@@ -53,6 +53,20 @@ if (argv[0] === 'completion' && argv.length >= 2) {
     }
     // Unknown shell — fall through to full path for proper error handling
 }
+// Hosted setup and hosted dispatch run before local adapter discovery. This is
+// the mode boundary: hosted mode must not read ~/.webcmd/clis or local site
+// memory just to decide what commands exist.
+if (argv[0] === 'setup') {
+    const { runHostedSetup } = await import('./hosted/setup.js');
+    process.exit(await runHostedSetup());
+}
+const { shouldUseHostedMode } = await import('./hosted/config.js');
+if (shouldUseHostedMode()) {
+    const { runHostedCli } = await import('./hosted/runner.js');
+    const result = await runHostedCli(argv);
+    if (result.handled)
+        process.exit(result.exitCode);
+}
 // Fast path: --get-completions — read from manifest, skip discovery
 const getCompIdx = process.argv.indexOf('--get-completions');
 if (getCompIdx !== -1) {

package/dist/src/release-notes.d.ts

@@ -1,5 +1,8 @@
 export declare const RELEASE_NOTE_SECTIONS: readonly ["Highlights", "Improvements", "Fixes", "Adapters", "Reverts"];
 export type ReleaseNoteSection = typeof RELEASE_NOTE_SECTIONS[number];
+export interface NormalizeReleaseNotesOptions {
+    context?: ReleaseContext;
+}
 export interface PullRequestLabel {
     name: string;
 }
@@ -33,8 +36,10 @@ export interface CompareCommit {
 }
 export type GitRunner = (args: readonly string[]) => Promise<string>;
 export declare function releaseVersionFromTag(tag: string): string;
+export declare function isMajorRelease(context: Pick<ReleaseContext, 'tag' | 'previousTag'>): boolean;
+export declare function releaseContributorHandles(pullRequests: PullRequestDetails[]): string[];
 export declare function replaceChangelogReleaseNotes(changelog: string, tag: string, notes: string): string;
 export declare function extractPullRequestNumber(message: string): number | null;
 export declare function filterReleasePullRequests(prs: PullRequestDetails[]): PullRequestDetails[];
-export declare function normalizeReleaseNotes(raw: string): string;
+export declare function normalizeReleaseNotes(raw: string, options?: NormalizeReleaseNotesOptions): string;
 export declare function buildReleaseNotesPrompt(context: ReleaseContext): string;

package/dist/src/release-notes.js

@@ -8,6 +8,24 @@ export const RELEASE_NOTE_SECTIONS = [
 const SQUASH_MERGE_PR_NUMBER_PATTERN = /\(#(?<number>\d+)\)\s*$/;
 const MERGE_COMMIT_PR_NUMBER_PATTERN = /^Merge pull request #(?<number>\d+) /;
 const RELEASE_PLEASE_TITLE_PATTERN = /^chore(?:\([^)]+\))?: release(?:\s|$)/;
+const SERVICE_ACCOUNT_HANDLES = new Set([
+    'allcontributors',
+    'copilot-pull-request-reviewer',
+    'dependabot',
+    'github-actions',
+    'release-please',
+    'renovate',
+    'semantic-release-bot',
+    'snyk-bot',
+    'web-flow',
+]);
+function normalizeHandle(handle) {
+    const trimmed = handle.trim();
+    return trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+}
+function uniqueSortedHandles(handles) {
+    return [...new Set(handles.map(normalizeHandle).filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}
 function isNoChangeContent(content) {
     const lines = content
         .split(/\r?\n/)
@@ -34,7 +52,11 @@ function formatReleaseNotesForChangelog(notes) {
     const trimmed = notes.trim();
     if (!trimmed)
         return '';
-    return trimmed.replace(/^##\s+/gm, '### ');
+    const lines = trimmed.split(/\r?\n/);
+    if (lines[0]?.startsWith('# ')) {
+        lines[0] = `_${lines[0].replace(/^#\s+/, '').trim()}_`;
+    }
+    return stripContributorAvatarLines(lines.join('\n')).replace(/^##\s+/gm, '### ');
 }
 export function releaseVersionFromTag(tag) {
     const value = tag.trim();
@@ -44,6 +66,143 @@ export function releaseVersionFromTag(tag) {
         return value.slice(1);
     return value;
 }
+function releaseDisplayVersionFromTag(tag) {
+    const version = releaseVersionFromTag(tag);
+    return version.startsWith('v') ? version : `v${version}`;
+}
+function parseReleaseSemver(tag) {
+    const match = releaseVersionFromTag(tag).match(/^v?(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:[-+].*)?$/);
+    if (!match?.groups)
+        return null;
+    return {
+        major: Number(match.groups.major),
+        minor: Number(match.groups.minor),
+        patch: Number(match.groups.patch),
+    };
+}
+export function isMajorRelease(context) {
+    const current = parseReleaseSemver(context.tag);
+    if (!current || current.major === 0)
+        return false;
+    const previous = parseReleaseSemver(context.previousTag);
+    if (!previous)
+        return current.minor === 0 && current.patch === 0;
+    return current.major > previous.major;
+}
+function isServiceAccount(handle) {
+    const normalized = normalizeHandle(handle).toLowerCase();
+    return SERVICE_ACCOUNT_HANDLES.has(normalized)
+        || normalized.endsWith('[bot]')
+        || normalized.endsWith('-bot');
+}
+export function releaseContributorHandles(pullRequests) {
+    return uniqueSortedHandles(pullRequests.flatMap((pr) => (pr.author?.login ? [pr.author.login] : []))).filter((handle) => !isServiceAccount(handle));
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        switch (character) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            case "'":
+                return '&#39;';
+            default:
+                return character;
+        }
+    });
+}
+function githubHandleUrl(handle) {
+    return `https://github.com/${encodeURIComponent(handle)}`;
+}
+function formatContributorAvatar(handle) {
+    const escapedHandle = escapeHtml(handle);
+    const encodedHandle = encodeURIComponent(handle);
+    return `<a href="${githubHandleUrl(handle)}" title="@${escapedHandle}"><img src="https://github.com/${encodedHandle}.png?size=64" width="64" height="64" alt="@${escapedHandle}" /></a>`;
+}
+function formatContributorLink(handle) {
+    return `[@${handle}](${githubHandleUrl(handle)})`;
+}
+function formatContributorsSection(handles) {
+    if (handles.length === 0)
+        return null;
+    return [
+        '## Contributors',
+        handles.map(formatContributorAvatar).join('\n'),
+        '',
+        handles.map(formatContributorLink).join(' | '),
+    ].join('\n');
+}
+function stripContributorAvatarLines(notes) {
+    return notes
+        .split(/\r?\n/)
+        .filter((line) => !(/<img\b/i.test(line) && /https:\/\/github\.com\/[^"'\s>]+\.png\?size=64/.test(line)))
+        .join('\n')
+        .replace(/(^|\n)(## Contributors)\n\n/g, '$1$2\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function parseMajorReleaseTitle(raw) {
+    for (const line of raw.split(/\r?\n/)) {
+        const titleMatch = line.match(/^#\s+(.+?)\s*$/);
+        if (titleMatch)
+            return titleMatch[1];
+        if (/^##\s+/.test(line))
+            return null;
+    }
+    return null;
+}
+function fallbackMajorReleaseTitle(context) {
+    const releaseText = context.pullRequests.map((pr) => [
+        pr.title,
+        ...pr.labels.map((label) => label.name),
+        ...pr.files.map((file) => file.path),
+    ].join('\n')).join('\n').toLowerCase();
+    if (/\bclis\//.test(releaseText) || /\badapter\b/.test(releaseText) || /\bcli\b/.test(releaseText)) {
+        return 'The Command Surface Expands';
+    }
+    if (/\bbrowser\b|\bcloak\b|\bdaemon\b/.test(releaseText)) {
+        return 'The Browser Runtime Matures';
+    }
+    if (/\bskills?\b/.test(releaseText)) {
+        return 'The Agent Authoring Edition';
+    }
+    if (/\bdocs?\b|\breadme\b/.test(releaseText)) {
+        return 'The Documentation Edition';
+    }
+    if (/\bplugins?\b/.test(releaseText)) {
+        return 'The Plugin System Opens Up';
+    }
+    return 'A New Command Surface';
+}
+function normalizeMajorReleaseTitle(rawTitle, context) {
+    const title = (rawTitle ?? '')
+        .replace(/^webcmd[-\s]+v?\d+\.\d+\.\d+(?:[-+][^:\s]+)?\s*:\s*/i, '')
+        .replace(/^webcmd\s*:\s*/i, '')
+        .replace(/[`*_]/g, '')
+        .replace(/\s+/g, ' ')
+        .replace(/^[#:\-\s]+/, '')
+        .replace(/[.!]+$/, '')
+        .trim();
+    const lowerTitle = title.toLowerCase();
+    if (!title
+        || title.length > 80
+        || lowerTitle === 'none'
+        || lowerTitle === 'n/a'
+        || lowerTitle === 'release notes'
+        || lowerTitle === 'webcmd'
+        || lowerTitle === 'webcmd release') {
+        return fallbackMajorReleaseTitle(context);
+    }
+    return title;
+}
+function formatMajorReleaseHeading(raw, context) {
+    return `# webcmd ${releaseDisplayVersionFromTag(context.tag)}: ${normalizeMajorReleaseTitle(parseMajorReleaseTitle(raw), context)}`;
+}
 export function replaceChangelogReleaseNotes(changelog, tag, notes) {
     const version = releaseVersionFromTag(tag);
     const headingPattern = new RegExp(`^## \\[${escapeRegExp(version)}\\]\\([^\\n]+\\) \\([^\\n]+\\)\\s*$`, 'm');
@@ -104,12 +263,24 @@ function parseReleaseNoteSections(raw) {
     }
     return sections;
 }
-export function normalizeReleaseNotes(raw) {
+export function normalizeReleaseNotes(raw, options = {}) {
     const sections = parseReleaseNoteSections(raw);
-    return RELEASE_NOTE_SECTIONS.flatMap((section) => {
+    const sectionBlocks = RELEASE_NOTE_SECTIONS.flatMap((section) => {
         const content = normalizeSectionContent(sections[section]?.join('\n'));
         return content ? [`## ${section}\n${content}`] : [];
-    }).join('\n\n');
+    });
+    if (sectionBlocks.length === 0)
+        return '';
+    const blocks = [];
+    if (options.context && isMajorRelease(options.context)) {
+        blocks.push(formatMajorReleaseHeading(raw, options.context));
+    }
+    blocks.push(...sectionBlocks);
+    const contributors = options.context ? releaseContributorHandles(options.context.pullRequests) : [];
+    const contributorsSection = formatContributorsSection(contributors);
+    if (contributorsSection)
+        blocks.push(contributorsSection);
+    return blocks.join('\n\n');
 }
 function formatPullRequest(pr) {
     const author = pr.author?.login ?? 'unknown';
@@ -128,11 +299,20 @@ function formatPullRequest(pr) {
 }
 export function buildReleaseNotesPrompt(context) {
     const prSummaries = context.pullRequests.map(formatPullRequest).join('\n\n');
+    const majorReleaseInstructions = isMajorRelease(context)
+        ? [
+            `This is a major release. Start with exactly one H1: # webcmd ${releaseDisplayVersionFromTag(context.tag)}: <Elegant Release Title>.`,
+            'Make the title grand enough to feel memorable, but polished rather than loud. Keep it short, specific to the supplied PRs, and avoid hype words.',
+        ]
+        : [
+            'Do not include a top-level release title.',
+        ];
     return [
         `Write user-facing release notes for ${context.tag}.`,
         `Release range: ${context.previousTag}...${context.currentRef}.`,
         'Use only the supplied pull requests below. Do not invent changes or pull in information from elsewhere.',
         `Allowed sections: ${RELEASE_NOTE_SECTIONS.map((section) => `## ${section}`).join(', ')}.`,
+        ...majorReleaseInstructions,
         'Include only sections that have user-visible changes. Omit empty sections entirely; do not write "None", "N/A", or similar placeholder text.',
         'Do not include a Contributors section.',
         'In this project, CLI commands and adapters are the same thing. Treat any PR that adds, removes, or changes files under clis/** as an adapter change, even if the PR title says "CLI" instead of "adapter".',

package/dist/src/release-notes.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, normalizeReleaseNotes, replaceChangelogReleaseNotes, } from './release-notes.js';
+import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, isMajorRelease, normalizeReleaseNotes, releaseContributorHandles, replaceChangelogReleaseNotes, } from './release-notes.js';
 describe('release notes helpers', () => {
     it('extracts PR numbers from squash and merge commit messages', () => {
         expect(extractPullRequestNumber('feat: add release notes (#123)')).toBe(123);
@@ -17,6 +17,22 @@ describe('release notes helpers', () => {
         ];
         expect(filterReleasePullRequests(prs).map((pr) => pr.number)).toEqual([1]);
     });
+    it('detects major releases from semver tag ranges', () => {
+        expect(isMajorRelease({ tag: 'webcmd-v2.0.0', previousTag: 'webcmd-v1.9.9' })).toBe(true);
+        expect(isMajorRelease({ tag: 'v3.1.0', previousTag: 'v2.9.9' })).toBe(true);
+        expect(isMajorRelease({ tag: 'webcmd-v2.1.0', previousTag: 'webcmd-v2.0.0' })).toBe(false);
+        expect(isMajorRelease({ tag: 'webcmd-v0.3.0', previousTag: 'webcmd-v0.2.5' })).toBe(false);
+    });
+    it('deduplicates PR author contributors and excludes service accounts', () => {
+        const prs = [
+            { number: 1, title: 'feat: browser polish', author: { login: 'alice' }, labels: [], files: [], url: 'https://example.com/1' },
+            { number: 2, title: 'feat: docs polish', author: { login: '@alice' }, labels: [], files: [], url: 'https://example.com/2' },
+            { number: 3, title: 'chore: release', author: { login: 'github-actions[bot]' }, labels: [], files: [], url: 'https://example.com/3' },
+            { number: 4, title: 'feat: adapter polish', author: { login: 'bob' }, labels: [], files: [], url: 'https://example.com/4' },
+            { number: 5, title: 'chore: release notes', author: { login: 'release-please' }, labels: [], files: [], url: 'https://example.com/5' },
+        ];
+        expect(releaseContributorHandles(prs)).toEqual(['alice', 'bob']);
+    });
     it('normalizes only sections with real release-note content', () => {
         const raw = [
             '## Highlights',
@@ -51,6 +67,83 @@ describe('release notes helpers', () => {
         expect(normalized).not.toContain('## Reverts');
         expect(normalized).not.toContain('None.');
     });
+    it('adds an elegant major release title and visual contributor credits', () => {
+        const context = {
+            tag: 'webcmd-v2.0.0',
+            previousTag: 'webcmd-v1.9.9',
+            currentRef: 'webcmd-v2.0.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: expand browser adapter coverage',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'clis/github/auth.js' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+                {
+                    number: 43,
+                    title: 'chore: release automation',
+                    author: { login: 'github-actions[bot]' },
+                    labels: [],
+                    files: [{ path: '.github/workflows/release.yml' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/43',
+                },
+            ],
+        };
+        const raw = [
+            '# webcmd v2.0.0: The Command Surface Opens',
+            '',
+            '## Highlights',
+            '- Broader adapter authoring workflows.',
+        ].join('\n');
+        const normalized = normalizeReleaseNotes(raw, { context });
+        expect(normalized).toContain('# webcmd v2.0.0: The Command Surface Opens');
+        expect(normalized).toContain('## Contributors');
+        expect(normalized).toContain('<img src="https://github.com/alice.png?size=64" width="64" height="64" alt="@alice" />');
+        expect(normalized).toContain('[@alice](https://github.com/alice)');
+        expect(normalized).not.toContain('github-actions');
+    });
+    it('uses a deterministic major release title fallback when the model omits one', () => {
+        const context = {
+            tag: 'webcmd-v2.0.0',
+            previousTag: 'webcmd-v1.9.9',
+            currentRef: 'webcmd-v2.0.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: add github adapter',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'clis/github/auth.js' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const normalized = normalizeReleaseNotes('## Highlights\n- Added a GitHub adapter.', { context });
+        expect(normalized).toContain('# webcmd v2.0.0: The Command Surface Expands');
+    });
+    it('does not add major release title treatment to minor releases', () => {
+        const context = {
+            tag: 'webcmd-v2.1.0',
+            previousTag: 'webcmd-v2.0.0',
+            currentRef: 'webcmd-v2.1.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: improve release notes',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'src/release-notes.ts' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const normalized = normalizeReleaseNotes('# The Polished Edition\n\n## Highlights\n- Better notes.', { context });
+        expect(normalized).not.toContain('# webcmd v2.1.0');
+        expect(normalized).toContain('## Highlights\n- Better notes.');
+        expect(normalized).toContain('## Contributors');
+    });
     it('replaces a matching changelog release entry with generated notes', () => {
         const changelog = [
             '# Changelog',
@@ -70,16 +163,26 @@ describe('release notes helpers', () => {
             '',
         ].join('\n');
         const notes = [
+            '# webcmd v2.0.0: The Command Surface Expands',
+            '',
             '## Highlights',
             '- Better release notes.',
             '',
             '## Adapters',
             '- Improved district checkout.',
+            '',
+            '## Contributors',
+            '<a href="https://github.com/alice" title="@alice"><img src="https://github.com/alice.png?size=64" width="64" height="64" alt="@alice" /></a>',
+            '',
+            '[@alice](https://github.com/alice)',
         ].join('\n');
         const updated = replaceChangelogReleaseNotes(changelog, 'webcmd-v0.2.3', notes);
         expect(updated).toContain('## [0.2.3]');
+        expect(updated).toContain('_webcmd v2.0.0: The Command Surface Expands_');
         expect(updated).toContain('### Highlights\n- Better release notes.');
         expect(updated).toContain('### Adapters\n- Improved district checkout.');
+        expect(updated).toContain('### Contributors\n[@alice](https://github.com/alice)');
+        expect(updated).not.toContain('<img');
         expect(updated).not.toContain('release-please generated note');
         expect(updated).toContain('## [0.2.2]');
         expect(updated).toContain('* older note');
@@ -109,6 +212,7 @@ describe('release notes helpers', () => {
         expect(prompt).toContain('## Highlights');
         expect(prompt).toContain('## Adapters');
         expect(prompt).not.toContain('## Contributors');
+        expect(prompt).toContain('Do not include a top-level release title');
         expect(prompt).toContain('Omit empty sections entirely');
         expect(prompt).toContain('Do not include a Contributors section');
         expect(prompt).toContain('CLI commands and adapters are the same thing');
@@ -116,4 +220,27 @@ describe('release notes helpers', () => {
         expect(prompt).toContain('Put new site adapters/CLIs, adapter promotions, adapter hardening');
         expect(prompt).toContain('## Reverts');
     });
+    it('asks for a tasteful H1 title only when building major release notes', () => {
+        const context = {
+            tag: 'webcmd-v2.0.0',
+            previousTag: 'webcmd-v1.9.9',
+            currentRef: 'webcmd-v2.0.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: expand adapter authoring',
+                    body: 'Adds richer authoring workflows.',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'skills/webcmd-adapter-author/SKILL.md' }],
+                    diff: 'diff --git a/skills/webcmd-adapter-author/SKILL.md b/skills/webcmd-adapter-author/SKILL.md',
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const prompt = buildReleaseNotesPrompt(context);
+        expect(prompt).toContain('This is a major release');
+        expect(prompt).toContain('# webcmd v2.0.0: <Elegant Release Title>');
+        expect(prompt).toContain('grand enough to feel memorable, but polished rather than loud');
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"

package/scripts/generate-release-notes.ts

@@ -245,7 +245,7 @@ export async function runGenerateReleaseNotes(
     const model = env.GEMINI_RELEASE_NOTES_MODEL || DEFAULT_MODEL;
     const prompt = buildReleaseNotesPrompt(context);
     const raw = await (deps.generateText ?? generateText)(prompt, model, apiKey);
-    const normalized = normalizeReleaseNotes(raw);
+    const normalized = normalizeReleaseNotes(raw, { context });
     if (normalized) {
       io.writeStdout(`${normalized}\n`);
     }