feedbackbasket-cli 0.12.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,289 @@
+# Changelog
+
+## Unreleased
+
+## [3.0.0] - 2026-08-22
+
+### Added
+
+- Added all 31 versioned product-operation mappings, including note update and note deletion.
+- Added contract checks for commands, HTTP paths, confirmations, documentation, and package release safety.
+
+### Changed
+
+- High-impact agent commands now need `--yes`.
+- The CLI version now matches the MCP and agent contract version.
+
+---
+
+## [0.12.0] - 2026-07-13
+
+### Added
+
+- **Conversation controls** - enable or disable website visitor replies and native in-app follow-up replies independently from the CLI
+- **Threaded conversation output** - `feedback replies` now shows both team messages and visitor follow-ups in chronological order
+
+### Changed
+
+- **Mobile conversation guidance** - mobile status, breadcrumbs, README, and the packaged skill now cover SDK unread badges and same-thread replies
+- **Agent thread safety** - agents preserve follow-up context on the original feedback item instead of creating duplicate feedback entries
+
+---
+
+## [0.11.0] - 2026-07-13
+
+### Added
+
+- **Autonomous mobile setup** - `mobile setup`, `status`, `bundle-ids`, and `verify` let agents configure and confirm native or hosted mobile feedback without using the dashboard
+- **Safe mobile lifecycle controls** - mobile integrations can be disabled or have their publishable project key rotated through explicit confirmation commands
+- **Mobile setup guidance** - agent output includes Swift package details, hosted-form configuration, supported frameworks, and connection metadata
+- **Native in-app replies** - the CLI recognizes mobile reply threads and supports `--delivery in-app` for responses displayed by the Swift SDK
+
+### Changed
+
+- **Publishable key safety** - mobile project keys are masked by default and are returned only when `--include-publishable-key` is explicitly supplied
+- **Safe mobile breadcrumbs** - generated follow-up commands fall back to resolved project IDs when a typed project reference contains shell-active characters
+- **Agent skill coverage** - the packaged skill now detects mobile frameworks, performs CLI-backed setup, protects private CLI/API credentials, and verifies SDK heartbeats
+- **Reply-channel guidance** - feedback details distinguish native in-app replies from website-widget replies so agents choose the correct delivery method
+
+---
+
+## [0.10.0] - 2026-07-10
+
+### Added
+
+- **Waitlist capture mode** - `widget settings --capture-mode waitlist|feedback` switches the installed project script between waitlist and feedback capture
+- **Waitlist management** - `waitlist list` supports search and pagination, while `waitlist export` provides the dashboard CSV from the terminal
+- **Widget security settings** - configure automatic error tracking and visitor-approved console error sharing from the CLI
+
+### Changed
+
+- **Inline widget trigger safety** - docs and packaged skill now explicitly tell agents to use `openFeedbackForm()` instead of internal widget methods such as `open()` or `openModal()`
+- **Waitlist integration guidance** - `widget script`, README, and the packaged skill explain how to annotate existing forms for waitlist capture
+- **Native HTTP client** - removed Axios and its transitive dependency tree in favor of Node's built-in `fetch`
+
+---
+
+## [0.9.3] - 2026-06-19
+
+### Changed
+
+- **Agent issue filing guidance** - the packaged skill now explains how agents should file discovered issues into the right FeedbackBasket project with short descriptions and structured metadata
+
+---
+
+## [0.9.2] - 2026-06-12
+
+### Changed
+
+- **Project URL safety** - `projects create` and `projects update --url` now require explicit confirmation before saving localhost URLs, and agent mode requires `--allow-local-url`
+- **Packaged skill docs** - agents now ask for the real website URL instead of using localhost, and keep basic modal feedback as the default unless guided feedback is requested
+- **Widget project selection** - agents now resolve the FeedbackBasket project for the current app instead of relying on the CLI default project when installing widgets
+- **Widget guidance** - README, help text, and breadcrumbs no longer nudge users to enable guided feedback by default
+
+---
+
+## [0.9.1] - 2026-06-12
+
+### Changed
+
+- **Inline widget trigger guidance** - `widget script` now shows custom button examples for inline widgets, including trigger-aware popup anchoring
+- **Packaged skill docs** - agents now use `openFeedbackForm({ trigger: event.currentTarget })` when installing custom inline trigger buttons
+
+---
+
+## [0.9.0] - 2026-06-11
+
+### Added
+
+- **Widget reply delivery** - `feedback reply` now supports `--delivery email|widget|both` so agents can reply in the widget thread, by email, or both
+- **Widget thread visibility** - `feedback show` now includes whether feedback has an active widget thread
+
+### Changed
+
+- **Agent reply safety guidance** - the packaged skill now requires agents to verify reply delivery method before responding
+
+---
+
+## [0.8.0] - 2026-06-11
+
+### Added
+
+- **`feedbackbasket feedback create`** - create feedback from the terminal with project, type, category, status, email, page URL, metadata, and agent JSON output support
+
+### Changed
+
+- **Agent reply safety guidance** - the packaged skill now tells agents to ask for a reply-to email before sending email replies when no project default is configured, and to use widget/dashboard replies for widget-only feedback
+
+---
+
+## [0.7.0] - 2026-06-10
+
+### Added
+
+- **Prefilled email widget settings** - `widget settings` can now configure read-only prefilled emails and hide the email field only when a runtime email is provided
+- **Feedback metadata output** - `feedback show` displays submitted widget metadata when available, and agent JSON output includes the metadata payload returned by the API
+
+---
+
+## [0.6.1] - 2026-06-08
+
+### Fixed
+
+- **Attachment links in feedback output** — `feedback show` now displays submitted screenshot/image URLs, and feedback/bug JSON responses include attachment metadata for agents
+
+---
+
+## [0.6.0] - 2026-06-07
+
+### Added
+
+- **`feedbackbasket widget flow`** — view, enable, reset, or apply JSON configs for guided feedback types and follow-up questions
+- **Expanded widget settings flags** — configure button size, radius, icon, email visibility, attachments, branding, z-index, and guided mode from the CLI
+- **Submitted details in feedback output** — `feedback show` now displays visitor-selected feedback type and follow-up answers
+
+### Changed
+
+- **Agent skill docs** — updated widget setup guidance so agents can customize guided feedback flows during installation
+
+---
+
+## [0.5.0] - 2026-05-10
+
+### Added
+
+- **`feedbackbasket login --manual`** — authenticate remote servers by approving in a browser and pasting the generated CLI token back into the terminal
+
+### Changed
+
+- **Clearer manual-login guidance** — `--manual` is documented as the flow for servers that cannot receive the localhost browser callback, while still requiring outbound HTTPS
+- **CLI token validation** — login now rejects MCP API keys (`fb_key_...`) with a clear hint because CLI login requires `fb_cli_...` tokens
+
+---
+
+## [0.4.0] - 2026-04-15
+
+### Added
+
+- **`feedback reply <id> "<content>"`** — send an email reply directly to the feedback submitter. The customer receives a branded email with your reply and the original feedback, and their response goes to the configured reply-to address
+- **`feedback replies <id>`** — list all replies sent for a feedback item (content, reply-to, who sent it, timestamp)
+- **`--reply-to <email>` on `feedback reply`** — override the project's default reply-to for a single reply
+- **`--reply-to <email>` on `projects update`** — set or clear the default reply-to email for a project (e.g. `projects update myapp --reply-to vlad@example.com`)
+- **Interactive reply-to prompt** — when sending a reply with no `--reply-to` and no project default, the CLI asks the human whether to use their account email or enter a custom one (agent mode returns a clear error asking the agent to pass `--reply-to` or set a project default)
+- **`replyToEmail` in project detail** — `projects show` now displays the configured reply-to address
+
+### API Endpoints
+
+- `POST /api/v1/feedback/:id/replies` — send reply (requires `full` scope)
+- `GET /api/v1/feedback/:id/replies` — list replies
+- `PATCH /api/v1/projects/:id` — now accepts `replyToEmail` in the body
+
+---
+
+## [0.3.5] - 2026-03-27
+
+### Fixed
+
+- **Name resolution for `--project` flag**: `feedback list --project prontoshoot` and `bugs list --project prontoshoot` now resolve names to IDs — previously returned empty results when using names
+
+### Changed
+
+- **Project name in list output**: Bug list and feedback list now show the project name (in green) instead of just the ID — much easier to scan across projects
+
+---
+
+## [0.3.3] - 2026-03-27
+
+### Added
+
+- **`--all` flag**: `feedback list --all` and `bugs list --all` to query across all projects, bypassing the default project filter
+
+---
+
+## [0.3.2] - 2026-03-27
+
+### Changed
+
+- **Custom help output**: Basecamp-style grouped sections (CORE COMMANDS, SHORTCUTS, SEARCH & EXPORT, AUTH & CONFIG, FLAGS, EXAMPLES, LEARN MORE)
+- **Short flags**: `-j` for `--json`, `-q` for `--quiet`, `-m` for `--md`
+- **Branded header**: "FeedbackBasket CLI v0.3.2" with logo in help output
+
+---
+
+## [0.3.1] - 2026-03-27
+
+### Fixed
+
+- **Login redirect flow**: Users who aren't logged in are now seamlessly redirected back to the CLI authorize page after login — no more needing to click the link twice
+
+### Added
+
+- **Skills repo**: Standalone [feedbackbasket-skills](https://github.com/deifos/feedbackbasket-skills) repo with install.md and enhanced SKILL.md
+- **CLI docs page**: New `/docs/cli` page on feedbackbasket.com with full command reference and terminal demo
+- **Landing page updates**: CLI feature card, dark terminal mockup, "Agent-Ready CLI" positioning
+- **Published to npm**: `npm install -g feedbackbasket-cli` now available
+
+---
+
+## [0.3.0] - 2026-03-26
+
+### Added
+
+- **Feedback delete**: `feedback delete <id>` — permanently remove feedback items with confirmation prompt
+- **Bulk status update**: `feedback bulk-update --status CLOSED --ids id1,id2,id3` — update multiple items at once
+- **Feedback export**: `feedback export [project] --format csv|md|json` — export all feedback to CSV, Markdown, or JSON
+- **Widget management**: `widget settings [project]` — view and update widget configuration (color, label, position, messages, etc.)
+- **Widget embed code**: `widget script [project]` — get the embed script tag ready to paste into HTML
+- **Team management**: `team list`, `team role <id> --role admin`, `team remove <id>` — manage organization members
+- **Note edit/delete**: API support for editing and deleting feedback notes (via PATCH/DELETE endpoints)
+
+### Changed
+
+- **Feedback commands expanded**: `feedback` now has 8 subcommands (list, show, search, update, note, delete, bulk-update, export)
+
+---
+
+## [0.2.0] - 2026-03-26
+
+### Added
+
+- **Project CRUD**: `projects create`, `projects show`, `projects update`, `projects delete` — full project management from the CLI
+- **Name resolution**: All project commands accept name or ID (e.g. `projects show feedbackbasket` instead of passing a cuid)
+- **Fuzzy matching**: Typo suggestions ("Did you mean: feedbackbasket?") and ambiguity detection when multiple projects match
+- **Top-level aliases**: `feedbackbasket login` and `feedbackbasket logout` (no need to type `auth login`)
+- **Project alias**: `feedbackbasket project` works as alias for `feedbackbasket projects`
+- **Onboarding wizard**: Multi-step first-login flow — authenticate, select default project, install Claude Code skill
+- **Default project**: Set during onboarding or via config — auto-applied to `feedback list`, `bugs list`, etc. (override with `--project`)
+
+### Changed
+
+- **Full access by default**: Auth login now defaults to `--scope full` (like Basecamp), no more read-only by default
+- **Brand colors**: All terminal output uses FeedbackBasket green (#22c55e) accent instead of generic cyan
+- **Centralized theme**: New `src/output/theme.ts` with brand colors, semantic helpers, and logo renderer
+- **Doctor command**: Now shows branded "FeedbackBasket CLI Diagnostics" header with logo
+- **Login flow**: Shows branded "FeedbackBasket CLI" header with green URL during browser auth
+- **Better error messages**: Auth and project fetch errors now show the actual error message instead of silent failures
+- **Delete confirmation**: `projects delete` prompts for confirmation in interactive mode (skipped with `--yes` or `--agent`)
+
+---
+
+## [0.1.0] - 2026-03-25
+
+### Added
+
+- Initial release of the FeedbackBasket CLI
+- **Authentication**: Browser-based OAuth flow (`auth login`) and manual token input (`auth login --token`)
+- **Auth management**: `auth status`, `auth logout`, `auth token` commands
+- **Projects**: `projects list` — view all accessible projects with feedback stats
+- **Feedback**: `feedback list` with filtering (--project, --category, --status, --sentiment, --search, --limit, --offset, --notes)
+- **Feedback detail**: `feedback show <id>` — view single feedback item with full details
+- **Feedback search**: `feedback search <query>` — cross-project text search
+- **Feedback write**: `feedback update <id>` — update status, category, sentiment (requires full scope)
+- **Feedback notes**: `feedback note <id> "<content>"` — add internal notes (requires full scope)
+- **Bug reports**: `bugs list` with severity/status filtering, `bugs stats` for summary
+- **Diagnostics**: `doctor` command — health checks for auth, connectivity, and integrations
+- **Agent integration**: `setup claude` — install SKILL.md for Claude Code
+- **Output modes**: Auto-detect (styled TTY / JSON piped), `--json` (envelope with breadcrumbs), `--quiet`/`--agent` (raw data), `--md` (Markdown)
+- **JSON envelope**: Basecamp-inspired `{ ok, data, summary, breadcrumbs }` response format
+- **Structured errors**: Error codes, exit codes, and recovery hints
+- **Credential storage**: `~/.config/feedbackbasket/credentials.json` with `FEEDBACKBASKET_TOKEN` env var support

package/README.md

@@ -26,7 +26,9 @@ feedbackbasket feedback create "Login button is broken" --project myapp --type b
 feedbackbasket bugs list --severity high
 ```
 
-The first time you log in, a setup wizard walks you through selecting a default project and installing the Claude Code skill.
+The first time you log in, a setup wizard walks you through selecting a default project and installing the Claude Code skill.
+
+The CLI uses agent surface version `3.0.0`. CLI login accepts only private CLI credentials. It does not accept MCP keys. Use `--yes` for high-impact commands in agent or machine mode. Interactive use can show a confirmation prompt.
 
 ## Agent Usage
 
@@ -50,7 +52,47 @@ When installing or configuring a widget for the current app, agents should not r
 feedbackbasket setup claude
 ```
 
-## Commands
+<!-- BEGIN GENERATED AGENT CAPABILITIES -->
+## Agent capability contract
+
+Agent surface version: `3.0.0`. The CLI and both MCP transports implement the same 31 product operations.
+
+| Product operation | CLI command | MCP tool | Required access | Confirm |
+| --- | --- | --- | --- | --- |
+| `projects.list` | `projects list` | `list_projects` | `read:projects` | No |
+| `projects.get` | `projects show` | `get_project` | `read:projects; allowed project` | No |
+| `projects.create` | `projects create` | `create_project` | `write:projects; unrestricted key` | No |
+| `projects.update` | `projects update` | `update_project` | `write:projects; allowed project` | No |
+| `projects.delete` | `projects delete` | `delete_project` | `write:projects; allowed project` | Yes |
+| `feedback.list` | `feedback list` | `get_feedback` | `read:feedback; allowed project` | No |
+| `feedback.get` | `feedback show` | `get_feedback_item` | `read:feedback; allowed project` | No |
+| `feedback.search` | `feedback search` | `search_feedback` | `read:feedback; allowed project` | No |
+| `feedback.create` | `feedback create` | `create_feedback` | `write:feedback; allowed project` | No |
+| `feedback.update` | `feedback update` | `update_feedback` | `write:feedback; allowed project` | No |
+| `feedback.delete` | `feedback delete` | `delete_feedback` | `write:feedback; allowed project` | Yes |
+| `feedback.bulkUpdate` | `feedback bulk-update` | `bulk_update_feedback` | `write:feedback; allowed project` | Yes |
+| `feedback.export` | `feedback export` | `export_feedback` | `read:feedback; allowed project` | No |
+| `bugs.list` | `bugs list` | `get_bug_reports` | `read:feedback; allowed project` | No |
+| `bugs.stats` | `bugs stats` | `get_bug_stats` | `read:feedback; allowed project` | No |
+| `notes.create` | `feedback note` | `create_feedback_note` | `write:notes; allowed project` | No |
+| `notes.update` | `feedback note update` | `update_feedback_note` | `write:notes; allowed project` | No |
+| `notes.delete` | `feedback note delete` | `delete_feedback_note` | `write:notes; allowed project` | Yes |
+| `replies.list` | `feedback replies` | `list_feedback_replies` | `read:feedback; allowed project` | No |
+| `replies.send` | `feedback reply` | `send_feedback_reply` | `write:replies; allowed project` | Yes |
+| `widget.getSettings` | `widget settings` | `get_widget_settings` | `read:projects; allowed project` | No |
+| `widget.updateSettings` | `widget update`<br>`widget flow` | `update_widget_settings` | `write:widget; allowed project` | No |
+| `widget.getScript` | `widget script` | `get_widget_script` | `read:projects; allowed project` | No |
+| `mobile.get` | `mobile status`<br>`mobile verify` | `get_mobile_integration` | `read:projects; allowed project` | No |
+| `mobile.update` | `mobile setup`<br>`mobile bundle`<br>`mobile conversations`<br>`mobile disable` | `update_mobile_integration` | `write:mobile; allowed project` | No |
+| `mobile.rotateKey` | `mobile rotate-key` | `rotate_mobile_project_key` | `write:mobile; allowed project` | Yes |
+| `waitlist.list` | `waitlist list` | `get_waitlist` | `read:feedback; allowed project` | No |
+| `waitlist.export` | `waitlist export` | `export_waitlist` | `read:feedback; allowed project` | No |
+| `team.list` | `team list` | `list_team_members` | `write:team; unrestricted key` | No |
+| `team.updateRole` | `team role` | `update_team_member_role` | `write:team; unrestricted key` | Yes |
+| `team.remove` | `team remove` | `remove_team_member` | `write:team; unrestricted key` | Yes |
+<!-- END GENERATED AGENT CAPABILITIES -->
+
+## Commands
 
 ### Authentication
 

package/dist/src/capabilities.d.ts

@@ -0,0 +1,38 @@
+import { type ProductOperationId } from 'feedbackbasket-agent-contract';
+export declare const CLI_CAPABILITIES: readonly {
+    operationId: ProductOperationId;
+    commands: readonly string[];
+}[];
+export declare const CLI_EXEMPTIONS: ({
+    readonly id: "auth";
+    readonly surface: "cli";
+    readonly reason: "Authentication is local CLI credential management, not a product operation.";
+} | {
+    readonly id: "login";
+    readonly surface: "cli";
+    readonly reason: "The login shortcut starts the local CLI authentication flow.";
+} | {
+    readonly id: "logout";
+    readonly surface: "cli";
+    readonly reason: "Logout removes a local CLI credential.";
+} | {
+    readonly id: "doctor";
+    readonly surface: "cli";
+    readonly reason: "Doctor checks local CLI configuration and connectivity.";
+} | {
+    readonly id: "setup";
+    readonly surface: "cli";
+    readonly reason: "Setup installs local agent guidance and does not change FeedbackBasket product data.";
+} | {
+    readonly id: "output";
+    readonly surface: "cli";
+    readonly reason: "Output flags change terminal formatting only.";
+} | {
+    readonly id: "initialize";
+    readonly surface: "mcp";
+    readonly reason: "MCP initialization is a transport protocol operation.";
+} | {
+    readonly id: "resources";
+    readonly surface: "mcp";
+    readonly reason: "Public MCP resources describe the service and do not access customer product data.";
+})[];

package/dist/src/capabilities.js

@@ -0,0 +1,6 @@
+import { PARITY_EXEMPTIONS, PRODUCT_OPERATIONS, } from 'feedbackbasket-agent-contract';
+export const CLI_CAPABILITIES = PRODUCT_OPERATIONS.map((operation) => ({
+    operationId: operation.id,
+    commands: operation.cli.commands,
+}));
+export const CLI_EXEMPTIONS = PARITY_EXEMPTIONS.filter(({ surface }) => surface === 'cli');

package/dist/src/cli.d.ts

@@ -1 +1,3 @@
+import { Command } from 'commander';
+export declare function createProgram(): Command;
 export declare function run(): void;

package/dist/src/cli.js

@@ -27,7 +27,7 @@ function resolveFormat(opts) {
 function getWriter() {
     return writer;
 }
-export function run() {
+export function createProgram() {
     const program = new Command('feedbackbasket')
         .version(VERSION, '-v, --version')
         .description('Command-line interface for FeedbackBasket')
@@ -71,6 +71,10 @@ export function run() {
     program.addCommand(createSetupCommand(getWriter));
     // Global error handler
     program.exitOverride();
+    return program;
+}
+export function run() {
+    const program = createProgram();
     (async () => {
         try {
             await program.parseAsync(process.argv);

package/dist/src/commands/auth.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import type { OutputWriter } from '../output/writer.js';
 export declare function createAuthCommand(getWriter: () => OutputWriter): Command;
+export declare function resolveAuthScope(value: string): 'read' | 'full';
 export declare function createLoginCommand(getWriter: () => OutputWriter): Command;
 export declare function createLogoutCommand(getWriter: () => OutputWriter): Command;

package/dist/src/commands/auth.js

@@ -23,7 +23,7 @@ export function createAuthCommand(getWriter) {
         .action(async (opts) => {
         const writer = getWriter();
         const config = loadConfig();
-        const scope = opts.scope === 'read' ? 'read' : 'full';
+        const scope = resolveAuthScope(opts.scope);
         const isInteractive = !writer.isMachineOutput() && process.stdin.isTTY;
         // ── Step 1: Authentication ──
         if (isInteractive) {
@@ -294,6 +294,11 @@ export function createAuthCommand(getWriter) {
     });
     return auth;
 }
+export function resolveAuthScope(value) {
+    if (value === 'read' || value === 'full')
+        return value;
+    throw errUsage('Scope must be "read" or "full"');
+}
 // Top-level aliases: `feedbackbasket login` and `feedbackbasket logout`
 export function createLoginCommand(getWriter) {
     return new Command('login')

package/dist/src/commands/feedback-bulk-update.js

@@ -4,11 +4,13 @@ import { AuthManager } from '../auth/manager.js';
 import { loadConfig } from '../config/config.js';
 import { errAuth, errUsage } from '../output/errors.js';
 import { brand } from '../output/theme.js';
+import { requireHighImpactConfirmation } from '../confirmation.js';
 export function createFeedbackBulkUpdateCommand(getWriter) {
     return new Command('bulk-update')
         .description('Update status for multiple feedback items at once')
         .requiredOption('--status <status>', 'New status (OPEN, UNDER_REVIEW, PLANNED, IN_PROGRESS, COMPLETE, CLOSED)')
         .requiredOption('--ids <ids>', 'Comma-separated feedback IDs')
+        .option('--yes', 'Confirm the bulk update')
         .action(async (opts) => {
         const writer = getWriter();
         const client = requireClient();
@@ -16,6 +18,7 @@ export function createFeedbackBulkUpdateCommand(getWriter) {
         if (ids.length === 0) {
             throw errUsage('At least one ID is required', 'Example: --ids id1,id2,id3');
         }
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), `Update ${ids.length} feedback item${ids.length === 1 ? '' : 's'}?`, '--yes is required for a bulk update in machine mode.');
         const result = await client.bulkUpdateStatus(ids, opts.status);
         if (!writer.isMachineOutput()) {
             console.log(`  ${brand.success('✓')} Updated ${result.updated} feedback items to ${brand.bold(result.status)}`);

package/dist/src/commands/feedback-delete.js

@@ -4,7 +4,7 @@ import { AuthManager } from '../auth/manager.js';
 import { loadConfig } from '../config/config.js';
 import { errAuth } from '../output/errors.js';
 import { brand } from '../output/theme.js';
-import { confirm } from '../prompt.js';
+import { requireHighImpactConfirmation } from '../confirmation.js';
 export function createFeedbackDeleteCommand(getWriter) {
     return new Command('delete')
         .argument('<id>', 'Feedback ID to delete')
@@ -16,12 +16,8 @@ export function createFeedbackDeleteCommand(getWriter) {
         if (!opts.yes && !writer.isMachineOutput() && process.stdin.isTTY) {
             console.log(`  ${brand.warning('Warning:')} This will permanently delete feedback ${brand.bold(id)}`);
             console.log();
-            const confirmed = await confirm('  Delete this feedback?', false);
-            if (!confirmed) {
-                console.log(brand.muted('  Cancelled.'));
-                return;
-            }
         }
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), 'Delete this feedback?', '--yes is required to delete feedback in machine mode.');
         const result = await client.deleteFeedback(id);
         if (!writer.isMachineOutput()) {
             console.log(`  ${brand.success('✓')} Deleted feedback ${id}`);

package/dist/src/commands/feedback-note.js

@@ -4,15 +4,19 @@ import { AuthManager } from '../auth/manager.js';
 import { loadConfig } from '../config/config.js';
 import { errAuth, errUsage } from '../output/errors.js';
 import { brand } from '../output/theme.js';
+import { requireHighImpactConfirmation } from '../confirmation.js';
 export function createFeedbackNoteCommand(getWriter) {
-    return new Command('note')
-        .argument('<id>', 'Feedback ID to add a note to')
+    const note = new Command('note')
+        .argument('[id]', 'Feedback ID to add a note to')
         .argument('[content]', 'Note content (or use --content)')
         .description('Add an internal note to a feedback item')
         .option('--content <text>', 'Note content (alternative to positional argument)')
         .action(async (id, contentArg, opts) => {
         const writer = getWriter();
         const content = contentArg ?? opts.content;
+        if (!id) {
+            throw errUsage('Feedback ID is required', 'Example: feedbackbasket feedback note <id> "Your note here"');
+        }
         if (!content) {
             throw errUsage('Note content is required', 'Example: feedbackbasket feedback note <id> "Your note here"');
         }
@@ -30,6 +34,34 @@ export function createFeedbackNoteCommand(getWriter) {
             ],
         });
     });
+    note
+        .command('update <feedbackId> <noteId>')
+        .description('Update an internal feedback note')
+        .requiredOption('--content <text>', 'New note content')
+        .action(async (feedbackId, noteId, opts) => {
+        const writer = getWriter();
+        const client = requireClient();
+        const result = await client.updateNote(feedbackId, noteId, opts.content);
+        writer.ok(result, {
+            summary: `Updated note ${noteId}`,
+            breadcrumbs: [{ action: 'View feedback', cmd: `feedbackbasket feedback show ${feedbackId}` }],
+        });
+    });
+    note
+        .command('delete <feedbackId> <noteId>')
+        .description('Delete an internal feedback note')
+        .option('--yes', 'Confirm note deletion')
+        .action(async (feedbackId, noteId, opts) => {
+        const writer = getWriter();
+        const client = requireClient();
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), `Delete note ${noteId}?`, '--yes is required to delete a note in machine mode.');
+        const result = await client.deleteNote(feedbackId, noteId);
+        writer.ok(result, {
+            summary: `Deleted note ${noteId}`,
+            breadcrumbs: [{ action: 'View feedback', cmd: `feedbackbasket feedback show ${feedbackId}` }],
+        });
+    });
+    return note;
 }
 function requireClient() {
     const manager = new AuthManager();

package/dist/src/commands/feedback-reply.js

@@ -5,6 +5,7 @@ import { loadConfig } from '../config/config.js';
 import { errAuth, errUsage } from '../output/errors.js';
 import { brand } from '../output/theme.js';
 import { ask } from '../prompt.js';
+import { requireHighImpactConfirmation } from '../confirmation.js';
 const deliveryOptions = new Set(['email', 'widget', 'in-app', 'both']);
 export function createFeedbackReplyCommand(getWriter) {
     return new Command('reply')
@@ -14,6 +15,7 @@ export function createFeedbackReplyCommand(getWriter) {
         .option('--content <text>', 'Reply content (alternative to positional argument)')
         .option('--delivery <delivery>', 'Reply delivery (email, widget, in-app, both)', 'email')
         .option('--reply-to <email>', 'Reply-to email for email delivery')
+        .option('--yes', 'Confirm that the reply can be sent')
         .action(async (id, contentArg, opts) => {
         const writer = getWriter();
         const content = contentArg ?? opts.content;
@@ -61,6 +63,7 @@ export function createFeedbackReplyCommand(getWriter) {
         if (sendsWidget && !feedback.hasWidgetAccess) {
             throw errUsage('This feedback has no in-app or widget reply thread.', 'Use --delivery email for feedback with an email address, or ask the human how they want to respond.');
         }
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), `Send this reply by ${delivery}?`, '--yes is required to send a reply in machine mode.');
         const result = await client.sendReply(id, content, {
             replyToEmail: replyTo,
             destinations,

package/dist/src/commands/mobile.js

@@ -67,6 +67,7 @@ export function createMobileCommand(getWriter) {
     });
     mobile
         .command('bundle-ids [project]')
+        .alias('bundle')
         .description('Add or remove allowed iOS bundle IDs')
         .option('--add <bundle-id>', 'Bundle ID to add (repeatable)', collect, [])
         .option('--remove <bundle-id>', 'Bundle ID to remove (repeatable)', collect, [])

package/dist/src/commands/projects.js

@@ -5,6 +5,7 @@ import { loadConfig } from '../config/config.js';
 import { errAuth, errUsage } from '../output/errors.js';
 import { brand, divider } from '../output/theme.js';
 import { confirm } from '../prompt.js';
+import { requireHighImpactConfirmation } from '../confirmation.js';
 import { resolveProject } from '../resolve.js';
 export function createProjectsCommand(getWriter) {
     const projects = new Command('projects')
@@ -139,17 +140,12 @@ export function createProjectsCommand(getWriter) {
         const resolved = await resolveProject(client, idOrName);
         const id = resolved.id;
         const projectName = resolved.name;
-        // Confirmation (skip in agent mode or --yes)
         if (!opts.yes && !writer.isMachineOutput() && process.stdin.isTTY) {
             console.log(`  ${brand.warning('Warning:')} This will permanently delete project "${brand.bold(projectName)}"`);
             console.log(`  ${brand.muted('All feedback, notes, and settings will be lost.')}`);
             console.log();
-            const confirmed = await confirm(`  Delete "${projectName}"?`, false);
-            if (!confirmed) {
-                console.log(brand.muted('  Cancelled.'));
-                return;
-            }
         }
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), `Delete "${projectName}"?`, '--yes is required to delete a project in machine mode.');
         const result = await client.deleteProject(id);
         if (!writer.isMachineOutput()) {
             console.log(`  ${brand.success('✓')} Deleted project "${brand.bold(result.name)}"`);

package/dist/src/commands/team.js

@@ -4,7 +4,7 @@ import { AuthManager } from '../auth/manager.js';
 import { loadConfig } from '../config/config.js';
 import { errAuth, errUsage } from '../output/errors.js';
 import { brand, divider } from '../output/theme.js';
-import { confirm } from '../prompt.js';
+import { requireHighImpactConfirmation } from '../confirmation.js';
 export function createTeamCommand(getWriter) {
     const team = new Command('team')
         .description('Manage organization members');
@@ -31,12 +31,14 @@ export function createTeamCommand(getWriter) {
         .command('role <memberId>')
         .description('Update a member\'s role')
         .requiredOption('--role <role>', 'New role: admin or member')
+        .option('--yes', 'Confirm the role change')
         .action(async (memberId, opts) => {
         const writer = getWriter();
         const client = requireClient();
         if (!['admin', 'member'].includes(opts.role)) {
             throw errUsage('Role must be "admin" or "member"');
         }
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), `Change member ${memberId} to ${opts.role}?`, '--yes is required to change a team role in machine mode.');
         const result = await client.updateMemberRole(memberId, opts.role);
         if (!writer.isMachineOutput()) {
             console.log(`  ${brand.success('✓')} Updated ${brand.bold(result.name)} to ${brand.bold(result.role)}`);
@@ -57,13 +59,7 @@ export function createTeamCommand(getWriter) {
         .action(async (memberId, opts) => {
         const writer = getWriter();
         const client = requireClient();
-        if (!opts.yes && !writer.isMachineOutput() && process.stdin.isTTY) {
-            const confirmed = await confirm(`  Remove member ${memberId}?`, false);
-            if (!confirmed) {
-                console.log(brand.muted('  Cancelled.'));
-                return;
-            }
-        }
+        await requireHighImpactConfirmation(writer, Boolean(opts.yes), `Remove member ${memberId}?`, '--yes is required to remove a team member in machine mode.');
         const result = await client.removeMember(memberId);
         if (!writer.isMachineOutput()) {
             console.log(`  ${brand.success('✓')} Removed ${brand.bold(result.name)} (${result.email})`);

package/dist/src/commands/widget.js

@@ -50,6 +50,7 @@ export function createWidgetCommand(getWriter) {
     // --- widget settings ---
     widget
         .command('settings [project]')
+        .alias('update')
         .description('View or update widget settings')
         .option('--capture-mode <mode>', 'Capture mode (feedback, waitlist)')
         .option('--color <hex>', 'Button color (e.g. #22c55e)')

package/dist/src/confirmation.d.ts

@@ -0,0 +1,2 @@
+import type { OutputWriter } from './output/writer.js';
+export declare function requireHighImpactConfirmation(writer: OutputWriter, confirmedByFlag: boolean, question: string, hint: string): Promise<void>;

package/dist/src/confirmation.js

@@ -0,0 +1,11 @@
+import { errUsage } from './output/errors.js';
+import { confirm } from './prompt.js';
+export async function requireHighImpactConfirmation(writer, confirmedByFlag, question, hint) {
+    if (confirmedByFlag)
+        return;
+    if (writer.isMachineOutput() || !process.stdin.isTTY) {
+        throw errUsage(hint, `${hint} Re-run the command with --yes.`);
+    }
+    if (!(await confirm(`  ${question}`, false)))
+        throw errUsage('Action cancelled');
+}

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.12.0";
-export declare const USER_AGENT = "FeedbackBasket-CLI/0.12.0";
+export declare const VERSION: "3.0.0";
+export declare const USER_AGENT: string;

package/dist/src/version.js

@@ -1,2 +1,3 @@
-export const VERSION = '0.12.0';
+import { AGENT_SURFACE_VERSION } from 'feedbackbasket-agent-contract';
+export const VERSION = AGENT_SURFACE_VERSION;
 export const USER_AGENT = `FeedbackBasket-CLI/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feedbackbasket-cli",
-  "version": "0.12.0",
+  "version": "3.0.0",
   "description": "Command-line interface for FeedbackBasket — manage feedback and waitlists from your terminal",
   "type": "module",
   "main": "dist/src/cli.js",
@@ -12,7 +12,10 @@
     "test": "tsx --test tests/*.test.ts",
     "dev": "tsx bin/feedbackbasket.ts",
     "start": "node dist/bin/feedbackbasket.js",
-    "prepublishOnly": "npm run build"
+    "check:parity": "tsx scripts/check-parity.ts",
+    "docs:generate": "tsx scripts/generate-capabilities.ts",
+    "docs:check": "tsx scripts/generate-capabilities.ts --check",
+    "prepublishOnly": "npm run check:parity && npm run docs:check && npm test && npm run build"
   },
   "keywords": [
     "feedbackbasket",
@@ -31,6 +34,7 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^13.1.0",
+    "feedbackbasket-agent-contract": "3.0.0",
     "open": "^10.1.0"
   },
   "devDependencies": {
@@ -44,6 +48,7 @@
   "files": [
     "dist/**/*",
     "skills/**/*",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ]
 }

package/skills/feedbackbasket/SKILL.md

@@ -5,7 +5,9 @@ description: Manage FeedbackBasket projects, feedback, bugs, website widgets, mo
 
 # FeedbackBasket CLI
 
-Full command-line interface for managing feedback, waitlist signups, bug reports, projects, widgets, and teams in FeedbackBasket. Works with any AI agent that can run shell commands.
+Full command-line interface for managing feedback, waitlist signups, bug reports, projects, widgets, and teams in FeedbackBasket. Works with any AI agent that can run shell commands.
+
+The unified agent surface version is `3.0.0`. It has 31 product operations. The CLI, stdio MCP package, and live Streamable HTTP MCP server implement the same contract.
 
 ## Authentication
 
@@ -27,7 +29,17 @@ feedbackbasket doctor                  # Full diagnostics
 | `--quiet` | Raw JSON data only | Scripting |
 | `--md` | Markdown | Documentation |
 
-**Agent rule**: Always use `--agent` for programmatic access. Parse the JSON output directly.
+**Agent rule**: Always use `--agent` for programmatic access. Parse the JSON output directly.
+
+## MCP Workflow Selection
+
+Use the CLI when the agent has shell access and an existing CLI login. Use MCP when the host supports MCP tools. For MCP, use either the `feedbackbasket-mcp-server@3.0.0` stdio package or the direct Streamable HTTP endpoint at `https://feedbackbasket.com/.well-known/mcp`.
+
+CLI credentials and MCP keys are private and are not interchangeable. Never put a credential in source, command arguments, logs, prompts, snapshots, generated files, or final responses. Use the host credential store or an environment variable.
+
+MCP read keys can use read operations only. Full keys can use writes that their scopes permit. A project-restricted key can access only its allowed projects. Project creation and team operations need an unrestricted full key. If a write is denied, do not try a different security path. Ask the user for the required access.
+
+High-impact operations need explicit approval. MCP calls must include `confirm: true`. CLI agent or machine commands must include `--yes`. These rules apply to project deletion, feedback deletion, bulk feedback updates, note deletion, replies, mobile key rotation, team role changes, and team removal.
 
 ## Quick Reference
 
@@ -121,16 +133,18 @@ feedbackbasket feedback search "crash on mobile" --project <id> --limit 10
 # Write
 feedbackbasket feedback create "Login button is broken" --content "Clicking Log in does nothing in Safari." --project <id> --type bug
 feedbackbasket feedback create "Feature idea" --content "Let users export saved views." --project <id> --type feature --metadata source=agent
-feedbackbasket feedback update <id> --status PLANNED --category BUG --sentiment NEGATIVE
-feedbackbasket feedback note <id> "Investigating — appears related to auth flow"
-feedbackbasket feedback delete <id> --yes
-feedbackbasket feedback bulk-update --status CLOSED --ids id1,id2,id3
+feedbackbasket feedback update <id> --status PLANNED --category BUG --sentiment NEGATIVE
+feedbackbasket feedback note <id> "Investigating — appears related to auth flow"
+feedbackbasket feedback note update <id> <note-id> --content "Updated internal note"
+feedbackbasket feedback note delete <id> <note-id> --yes
+feedbackbasket feedback delete <id> --yes
+feedbackbasket feedback bulk-update --status CLOSED --ids id1,id2,id3 --yes
 
 # Reply to submitter by email, widget/in-app thread, or both
-feedbackbasket feedback reply <id> "Thanks for reporting — we pushed a fix!" --delivery email --reply-to support@example.com
-feedbackbasket feedback reply <id> "<content>" --delivery widget
-feedbackbasket feedback reply <id> "<content>" --delivery in-app
-feedbackbasket feedback reply <id> "<content>" --delivery both --reply-to support@example.com
+feedbackbasket feedback reply <id> "Thanks for reporting — we pushed a fix!" --delivery email --reply-to support@example.com --yes
+feedbackbasket feedback reply <id> "<content>" --delivery widget --yes
+feedbackbasket feedback reply <id> "<content>" --delivery in-app --yes
+feedbackbasket feedback reply <id> "<content>" --delivery both --reply-to support@example.com --yes
 feedbackbasket feedback replies <id>                                          # show the complete conversation
 
 # Export
@@ -182,7 +196,9 @@ Waitlist mode keeps the same project script and binds to the host app's own anno
 </form>
 ```
 
-Email is required and name is optional. Use `data-feedbackbasket-state="loading|success|error"` for custom UI, or listen for the bubbling `feedbackbasket:waitlist:success` and `feedbackbasket:waitlist:error` events. Do not add a competing submit handler.
+The form must be served from the website origin saved on the FeedbackBasket project. Email is required and name is optional. The script binds forms already on the page and forms added later, uses native browser validation, disables submit controls during the request, and keeps the host app's styling.
+
+Use `data-feedbackbasket-state="loading|success|error"` for custom UI. The bubbling `feedbackbasket:waitlist:success` event includes `detail.email` and `detail.duplicate`; `feedbackbasket:waitlist:error` includes `detail.message` and `detail.status`. Do not add a competing submit handler. Repeat submissions for the same project and email update the existing signup rather than creating a duplicate.
 
 ### Waitlist Signups
 
@@ -224,7 +240,7 @@ Use the basic widget experience by default: `displayMode` stays `modal`, and gui
 ### Team
 ```bash
 feedbackbasket team list
-feedbackbasket team role <memberId> --role admin
+feedbackbasket team role <memberId> --role admin --yes
 feedbackbasket team remove <memberId> --yes
 ```
 
@@ -316,10 +332,10 @@ feedbackbasket feedback show <id> --agent
 ```bash
 # Agent reads context, asks which delivery method to use, then sends it
 feedbackbasket feedback show <id> --agent                    # read email, replyChannel, project.replyToEmail
-feedbackbasket feedback reply <id> "<drafted response>" --delivery widget --agent
-feedbackbasket feedback reply <id> "<drafted response>" --delivery in-app --agent
-feedbackbasket feedback reply <id> "<drafted response>" --delivery email --reply-to support@example.com --agent
-feedbackbasket feedback reply <id> "<drafted response>" --delivery both --reply-to support@example.com --agent
+feedbackbasket feedback reply <id> "<drafted response>" --delivery widget --yes --agent
+feedbackbasket feedback reply <id> "<drafted response>" --delivery in-app --yes --agent
+feedbackbasket feedback reply <id> "<drafted response>" --delivery email --reply-to support@example.com --yes --agent
+feedbackbasket feedback reply <id> "<drafted response>" --delivery both --reply-to support@example.com --yes --agent
 feedbackbasket feedback update <id> --status COMPLETE --agent
 feedbackbasket feedback note <id> "Replied via CLI" --agent
 ```
@@ -381,10 +397,10 @@ Errors include hints:
 ## Invariants
 
 - Always authenticate before data commands
-- `--agent` flag suppresses all interactive prompts and confirmations
+- `--agent` suppresses interactive prompts. High-impact operations still need `--yes`.
 - Default project (set during login) is used when `--project` is not specified
 - Project names resolve case-insensitively with fuzzy matching
 - Write operations use full scope (granted by default during login)
 - Feedback IDs are stable CUIDs — safe to reference across commands
 - All timestamps are ISO 8601
-- `--yes` flag skips delete confirmations in interactive mode
+- `--yes` confirms all high-impact CLI operations in agent or machine mode