@cantinasecurity/apex-cli 0.1.0 → 0.1.2

package/.claude/skills/apex-cli/SKILL.md

@@ -19,20 +19,28 @@ Recommended workflow:
 4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
 6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+7. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
 
 If the Apex MCP server is not configured, fall back to the local CLI:
 
 - Prefer scripted commands over the interactive shell.
 - Use `--non-interactive` and `--no-open` for automation-friendly CLI calls.
 - Use `--json` whenever structured output is helpful.
+- `apex credits` reports standard credits and audit scan entitlements when Bedrock returns both balances.
 - Work from the target repository directory so Apex can resolve `.apex/workspace.json`.
+- `apex scan` scans the current working directory by default; pass `--repo` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Plain local directories and dirty git worktrees can scan through local snapshot uploads without provider access.
+- Audit scans use `--mode audit` in user-facing CLI calls. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
+- Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
+- Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
+- Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit `scanId` when needed, or use the finding UUID directly.
 
 ## Examples
 
 - Start a scan for the current repository or directory: run `apex-doctor`, bind a workspace if needed, then call `apex-scan`.
 - Check an active scan: call `apex-status`, then `apex-findings` when the scan completes.
 - Export findings for review: call `apex-export-findings` with `format` set to `markdown`, `json`, or `gitlab-sast`.
+- Leave review feedback: call `apex-finding-comment` to add a note, or `apex-finding-feedback` with `status` set to `valid` or `invalid`.

package/README.md

@@ -98,9 +98,12 @@ If Apex asks for a workspace name, that is the Apex workspace name for the curre
 Supported shell commands:
 
 - `/credits`
-- `/scan [standard|ultra]`
+- `/scan [standard|audit]`
 - `/scans`
 - `/findings [scan-id]`
+- `/findings comment <finding-id|finding-identifier> <comment>`
+- `/findings feedback <finding-id|finding-identifier> valid [comment]`
+- `/findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]`
 - `/export [scan-id]`
 - `/workspaces`
 - `/cancel-scan [scan-id]`
@@ -128,6 +131,8 @@ Supported shell commands:
 - `apex scan`
 - `apex scans`
 - `apex findings [--scan <scan-id>]`
+- `apex findings comment <finding-id|finding-identifier> --content <markdown> [--parent-comment <comment-id>] [--scan <scan-id>]`
+- `apex findings feedback <finding-id|finding-identifier> <valid|invalid> [comment] [--comment <markdown>] [--scan <scan-id>] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant]`
 - `apex export findings [--scan <scan-id>] [--format markdown|json|gitlab-sast] [--output <path>]`
 - `apex workspaces`
 - `apex workspace`
@@ -147,9 +152,33 @@ Helpful workspace flags:
 - `--company <id-or-handle>` to choose the Apex company when more than one is available
 - `--workspace-name <name>` to set the Apex workspace name for this directory
 
+`apex credits` shows standard scan credits plus audit scan entitlements when the server returns them.
+
+## Finding Review Feedback
+
+Finding review collaboration now has explicit write commands:
+
+- `apex findings comment <finding-id|finding-identifier> --content "Needs auth check"`
+- `apex findings feedback <finding-id|finding-identifier> valid --comment "Reproduced on latest build"`
+- `apex findings feedback <finding-id|finding-identifier> invalid --dismissal-reason false-positive --comment "This path is unreachable"`
+- `/findings comment <finding-ref> <comment>`
+- `/findings feedback <finding-ref> valid [comment]`
+- `/findings feedback <finding-ref> invalid <false-positive|by-design|not-relevant> [comment]`
+
+Identifiers such as `KERN2-25` are resolved against the selected or latest scan for the current workspace binding. Pass `--scan <scan-id>` when you need a specific scan, or pass the finding UUID directly to skip workspace-based resolution.
+
+Finding comments and valid/invalid feedback currently require a Cantina web session token in `CANTINA_AUTH_TOKEN`. Set it to the value of your logged-in `auth_token` cookie before using the write commands or the corresponding MCP tools.
+
+Invalid feedback requires a dismissal reason. Valid feedback can include `--suggested-severity extreme|critical|high|medium|low|informational`.
+
+This is intentionally documented as a separate auth requirement because the current Apex read APIs and finding review write APIs do not accept the same credentials:
+
+- read operations such as `apex findings`, `apex export findings`, and `apex-findings` use the Apex CLI device-login bearer token
+- finding comments and feedback currently go through the Cantina web-app routes and require `CANTINA_AUTH_TOKEN`
+
 ## Local Source Scans
 
-`apex scan` now works against any local source root you point it at:
+`apex scan` now works against any local source root you point it at. By default, that source root is the current working directory:
 
 - clean GitHub or GitLab checkouts can stay on the remote-materialization path
 - dirty git worktrees fall back to a local snapshot upload by default
@@ -157,12 +186,13 @@ Helpful workspace flags:
 
 Useful flags:
 
-- `--repo <path>` to scan one or more explicit local roots
+- `--repo <path>` to scan one or more explicit local roots instead of the current directory
 - `--source-mode auto|remote|local` to control remote-first fallback behavior
+- `--mode standard|audit` to choose the scan mode
 
 `auto` is the default. `remote` requires Apex to materialize from a remote repository. `local` forces a local snapshot upload even when a clean remote path is available.
 
-Ultra scans still require provider-backed GitHub or GitLab repositories that Apex can materialize remotely without a local snapshot fallback.
+Audit scans still require provider-backed GitHub or GitLab repositories that Apex can materialize remotely without a local snapshot fallback. `ultra` remains accepted as a backwards-compatible alias for the audit scan mode.
 
 ## LLM / MCP Usage
 
@@ -234,6 +264,7 @@ The MCP server exposes Apex-specific tools for:
 - doctor, credits, and provider connection URLs
 - workspace inspection and workspace binding
 - scan start, status, cancellation, findings, and findings export
+- finding comments and valid/invalid feedback with `apex-finding-comment` and `apex-finding-feedback`
 
 For repository-scoped operations, pass `cwd` explicitly so the server can resolve the right `.apex/workspace.json` binding and repository roots.
 
@@ -243,7 +274,7 @@ For Claude Code, the packaged project skill can be installed into the current re
 
 ## Development Notes
 
-The CLI uses the Apex `/api/cli/v2/**` local-source routes for scan planning and snapshot uploads, with legacy `/api/cli/v1/**` routes still used for provider-backed flows such as ultra scans. Local state is stored under:
+The CLI uses the Apex `/api/cli/v2/**` local-source routes for scan planning and snapshot uploads, with legacy `/api/cli/v1/**` routes still used for provider-backed flows such as audit scans. Local state is stored under:
 
 - `~/.config/apex/config.json`
 - `~/.config/apex/credentials.json`

package/dist/apex.js

@@ -1,6 +1,6 @@
 import { ApexApiClient, formatApiError } from "./api-client.js";
 import { parseArgs } from "./args.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandLogin, commandLogout, commandScan, commandScans, commandSetup, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { runMcpServer } from "./mcp.js";
 import { runInteractiveShell } from "./shell.js";
@@ -63,6 +63,32 @@ async function main() {
             await commandWorkspace(cwd, parsed.flags);
             return;
         case "findings":
+            if (parsed.subcommand === "comment") {
+                const findingRef = parsed.args[0] ?? "";
+                const content = parsed.args.slice(1).join(" ").trim() || String(parsed.flags.content ?? "");
+                await commandFindingComment(client, cwd, parsed.flags, findingRef, content, typeof parsed.flags["parent-comment"] === "string"
+                    ? parsed.flags["parent-comment"]
+                    : null);
+                return;
+            }
+            if (parsed.subcommand === "feedback") {
+                const findingRef = parsed.args[0] ?? "";
+                const feedbackType = parsed.args[1] ??
+                    (typeof parsed.flags.status === "string"
+                        ? parsed.flags.status
+                        : undefined);
+                if (feedbackType !== "valid" && feedbackType !== "invalid") {
+                    throw new Error("Usage: apex findings feedback <finding-id|finding-identifier> <valid|invalid> [--dismissal-reason false-positive|by-design|not-relevant]");
+                }
+                await commandFindingFeedback(client, cwd, parsed.flags, {
+                    requestedFindingRef: findingRef,
+                    feedbackType,
+                    comment: parsed.args.slice(2).join(" ").trim() || getFlagValue(parsed.flags.comment),
+                    suggestedSeverity: getFlagValue(parsed.flags["suggested-severity"]),
+                    dismissalReason: getFlagValue(parsed.flags["dismissal-reason"]),
+                });
+                return;
+            }
             await commandFindings(client, cwd, parsed.flags);
             return;
         case "export":
@@ -84,6 +110,9 @@ async function main() {
             throw new Error(`Unknown command: ${parsed.command}`);
     }
 }
+function getFlagValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
 main().catch((error) => {
     if (error instanceof Error && error.reported) {
         process.exitCode = 1;

package/dist/commands.js

@@ -3,7 +3,7 @@ import { logout } from "./auth.js";
 import { ApiError } from "./api-client.js";
 import { openInBrowser } from "./browser.js";
 import { loadConfig, saveConfig } from "./config.js";
-import { fetchScanExport, fetchScanFindings, resolveScanSelection } from "./findings.js";
+import { createFindingComment, fetchScanExport, fetchScanFindings, isFindingUuid, normalizeFindingRef, requireCantinaAuthToken, resolveFindingSelection, resolveScanSelection, submitFindingFeedback, } from "./findings.js";
 import { prepareExplicitScanSources, supportsLegacyRemoteFlow, } from "./local-source-scan.js";
 import { logLine, printJson, withLoadingIndicator } from "./output.js";
 import { confirm } from "./prompt.js";
@@ -18,6 +18,19 @@ import path from "node:path";
 const WORKSPACE_USE_PATTERN = "<workspace-name|workspace-prefix|workspace-id>";
 const WORKSPACE_BINDING_GUIDANCE = "Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const WORKSPACE_SELECTION_GUIDANCE = "Run `apex workspaces` to list available workspace names, prefixes, and IDs, then retry `apex workspace use \"<workspace name>\"`.";
+const FINDING_FEEDBACK_SEVERITIES = [
+    "extreme",
+    "critical",
+    "high",
+    "medium",
+    "low",
+    "informational",
+];
+const FINDING_DISMISSAL_REASONS = [
+    "false-positive",
+    "by-design",
+    "not-relevant",
+];
 async function saveCompanyDefault(companyId) {
     const config = await loadConfig();
     if (config.defaultCompanyId !== companyId) {
@@ -36,6 +49,64 @@ function getSuggestedWorkspaceRef(workspace) {
 function formatWorkspaceUseCommand(workspace) {
     return `apex workspace use ${formatCommandArgument(getSuggestedWorkspaceRef(workspace))}`;
 }
+function getOptionalCount(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : null;
+}
+function formatAuditScanBalance(scanBalance) {
+    const purchased = getOptionalCount(scanBalance.auditPurchased);
+    const used = getOptionalCount(scanBalance.auditUsed);
+    const remaining = getOptionalCount(scanBalance.auditRemaining);
+    const available = getOptionalCount(scanBalance.auditAvailable) ??
+        remaining ??
+        (purchased !== null && used !== null ? Math.max(0, purchased - used) : null);
+    if (purchased === null && used === null && available === null) {
+        return null;
+    }
+    const detailParts = [];
+    if (purchased !== null) {
+        detailParts.push(`${purchased} purchased`);
+    }
+    if (used !== null) {
+        detailParts.push(`${used} used`);
+    }
+    if (available !== null) {
+        const detailSuffix = detailParts.length ? ` (${detailParts.join(", ")})` : "";
+        return `Audit scans: ${available} available${detailSuffix}`;
+    }
+    return `Audit scans: ${detailParts.join(", ")}`;
+}
+function normalizeRequestedScanMode(value) {
+    return value === "ultra" || value === "audit" ? "ultra" : "standard";
+}
+function normalizeFindingRefInput(value) {
+    const trimmed = normalizeFindingRef(value);
+    if (!trimmed) {
+        throw new Error("A finding ID or finding identifier is required.");
+    }
+    return trimmed;
+}
+function normalizeFeedbackSeverity(value) {
+    const normalized = value?.trim() ?? "";
+    if (!normalized) {
+        return null;
+    }
+    if (FINDING_FEEDBACK_SEVERITIES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Suggested severity must be one of: ${FINDING_FEEDBACK_SEVERITIES.join(", ")}.`);
+}
+function normalizeDismissalReason(value) {
+    const normalized = value?.trim() ?? "";
+    if (!normalized) {
+        return null;
+    }
+    if (FINDING_DISMISSAL_REASONS.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Dismissal reason must be one of: ${FINDING_DISMISSAL_REASONS.join(", ")}.`);
+}
 async function requireWorkspaceBinding(cwd) {
     const binding = await loadWorkspaceBinding(cwd);
     if (binding) {
@@ -43,6 +114,27 @@ async function requireWorkspaceBinding(cwd) {
     }
     throw new Error(`This directory is not bound to an Apex workspace yet. ${WORKSPACE_BINDING_GUIDANCE}`);
 }
+function requireLoadedWorkspaceBinding(binding) {
+    if (binding) {
+        return binding;
+    }
+    throw new Error(`This directory is not bound to an Apex workspace yet. ${WORKSPACE_BINDING_GUIDANCE}`);
+}
+async function maybePersistFindingSelectionBinding(params) {
+    if (!params.binding || !params.scan) {
+        return params.binding;
+    }
+    const nextBinding = {
+        ...params.binding,
+        lastScanId: getScanDisplayId(params.scan),
+        lastScanUrl: params.response?.scan.scanUrl ??
+            params.scan.scanUrl ??
+            params.binding.lastScanUrl ??
+            null,
+    };
+    await saveWorkspaceBinding(params.cwd, nextBinding);
+    return nextBinding;
+}
 function canPromptForConfirmation(flags) {
     return !isNonInteractive(flags) && process.stdin.isTTY && process.stdout.isTTY;
 }
@@ -144,7 +236,15 @@ export async function commandCredits(client, cwd, flags) {
         return payload;
     }
     logLine(`Company: ${payload.company.handle ?? payload.company.id}`, flags);
-    logLine(`Credits: ${payload.scanBalance.remaining} remaining (${payload.scanBalance.purchased} purchased, ${payload.scanBalance.used} used)`, flags);
+    logLine(`Standard credits: ${payload.scanBalance.remaining} remaining (${payload.scanBalance.purchased} purchased, ${payload.scanBalance.used} used)`, flags);
+    const auditBalance = formatAuditScanBalance(payload.scanBalance);
+    if (auditBalance) {
+        logLine(auditBalance, flags);
+    }
+    const redeemableAuditScans = getOptionalCount(payload.scanBalance.auditRedeemableFromCredits);
+    if (redeemableAuditScans && redeemableAuditScans > 0) {
+        logLine(`Redeemable audit scans from standard credits: ${redeemableAuditScans}`, flags);
+    }
     logLine(`Scans enabled: ${payload.scansEnabled ? "yes" : "no"}`, flags);
     return payload;
 }
@@ -244,7 +344,7 @@ export async function commandScan(client, cwd, flags) {
     const me = await ensureAuthenticated(client, flags);
     const selection = await selectWorkspaceTarget(cwd, me, flags);
     const result = await withLoadingIndicator("Resolving workspace and scan plan...", flags, () => resolveWorkspaceSelection(client, selection));
-    const requestedMode = getFlagString(flags, "mode") === "ultra" ? "ultra" : "standard";
+    const requestedMode = normalizeRequestedScanMode(getFlagString(flags, "mode"));
     if (!result.resolve.workspaceId) {
         throw new Error("Workspace resolution did not return a workspaceId.");
     }
@@ -255,14 +355,14 @@ export async function commandScan(client, cwd, flags) {
     let scan;
     if (requestedMode === "ultra") {
         if (!supportsLegacyRemoteFlow(result.resolve.plannedSources)) {
-            throw new Error("Ultra scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.");
+            throw new Error("Audit scans currently require provider-backed GitHub or GitLab repositories without local snapshot fallbacks.");
         }
-        const legacyResolve = await withLoadingIndicator("Preparing ultra scan...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
+        const legacyResolve = await withLoadingIndicator("Preparing audit scan...", flags, () => resolveWorkspaceSelectionLegacy(client, selection, resolvedWorkspaceId));
         if (!legacyResolve.workspaceId) {
             throw new Error("Workspace resolution did not return a workspaceId.");
         }
         workspaceId = legacyResolve.workspaceId;
-        scan = await withLoadingIndicator("Starting ultra scan...", flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
+        scan = await withLoadingIndicator("Starting audit scan...", flags, () => client.request(`/api/cli/v1/local-workspaces/${encodeURIComponent(workspaceId)}/scan`, {
             method: "POST",
             json: {
                 mode: requestedMode,
@@ -560,6 +660,122 @@ export async function commandFindings(client, cwd, flags) {
     }
     return payload;
 }
+export async function commandFindingComment(client, cwd, flags, requestedFindingRef, content, parentCommentId) {
+    const findingRef = normalizeFindingRefInput(requestedFindingRef);
+    const trimmedContent = content.trim();
+    if (!trimmedContent) {
+        throw new Error("Usage: apex findings comment <finding-id|finding-identifier> --content \"<markdown>\"");
+    }
+    requireCantinaAuthToken();
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const needsWorkspaceResolution = !isFindingUuid(findingRef);
+    const binding = needsWorkspaceResolution
+        ? requireLoadedWorkspaceBinding(currentBinding)
+        : currentBinding;
+    if (needsWorkspaceResolution) {
+        await ensureAuthenticated(client, flags);
+    }
+    const selection = await withLoadingIndicator("Resolving finding...", flags, () => resolveFindingSelection({
+        client,
+        binding,
+        requestedFindingRef: findingRef,
+        requestedScanId: getFlagString(flags, "scan"),
+    }));
+    const response = await withLoadingIndicator("Adding finding comment...", flags, () => createFindingComment(client, selection.findingId, {
+        content: trimmedContent,
+        parentCommentId: parentCommentId?.trim() || null,
+    }));
+    const nextBinding = await maybePersistFindingSelectionBinding({
+        cwd,
+        binding,
+        scan: selection.scan,
+        response: selection.response,
+    });
+    const payload = {
+        binding: nextBinding,
+        scan: selection.scan,
+        findingId: selection.findingId,
+        findingRef: selection.findingRef,
+        finding: selection.finding,
+        comment: response.comment,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Finding: ${selection.finding?.findingIdentifier ?? selection.findingId}`, flags);
+    logLine(`Comment: added (${response.comment.id})`, flags);
+    logLine(`Author: ${response.comment.user.name}`, flags);
+    logLine(`Created: ${response.comment.createdAt}`, flags);
+    return payload;
+}
+export async function commandFindingFeedback(client, cwd, flags, params) {
+    const findingRef = normalizeFindingRefInput(params.requestedFindingRef);
+    const suggestedSeverity = normalizeFeedbackSeverity(params.suggestedSeverity);
+    const dismissalReason = normalizeDismissalReason(params.dismissalReason);
+    if (params.feedbackType === "valid" &&
+        dismissalReason) {
+        throw new Error("Dismissal reasons are only valid for invalid feedback.");
+    }
+    if (params.feedbackType === "invalid" &&
+        suggestedSeverity) {
+        throw new Error("Suggested severity is only valid for valid feedback.");
+    }
+    if (params.feedbackType === "invalid" && !dismissalReason) {
+        throw new Error("Invalid feedback requires a dismissal reason.");
+    }
+    requireCantinaAuthToken();
+    const currentBinding = await loadWorkspaceBinding(cwd);
+    const needsWorkspaceResolution = !isFindingUuid(findingRef);
+    const binding = needsWorkspaceResolution
+        ? requireLoadedWorkspaceBinding(currentBinding)
+        : currentBinding;
+    if (needsWorkspaceResolution) {
+        await ensureAuthenticated(client, flags);
+    }
+    const selection = await withLoadingIndicator("Resolving finding...", flags, () => resolveFindingSelection({
+        client,
+        binding,
+        requestedFindingRef: findingRef,
+        requestedScanId: getFlagString(flags, "scan"),
+    }));
+    const response = await withLoadingIndicator("Submitting finding feedback...", flags, () => submitFindingFeedback(client, selection.findingId, {
+        feedbackType: params.feedbackType,
+        comment: params.comment?.trim() || null,
+        suggestedSeverity,
+        dismissalReason,
+    }));
+    const nextBinding = await maybePersistFindingSelectionBinding({
+        cwd,
+        binding,
+        scan: selection.scan,
+        response: selection.response,
+    });
+    const payload = {
+        binding: nextBinding,
+        scan: selection.scan,
+        findingId: selection.findingId,
+        findingRef: selection.findingRef,
+        finding: selection.finding,
+        feedback: response.feedback,
+    };
+    if (isJsonMode(flags)) {
+        printJson(payload);
+        return payload;
+    }
+    logLine(`Finding: ${selection.finding?.findingIdentifier ?? selection.findingId}`, flags);
+    logLine(`Feedback: ${response.feedback.feedbackType ?? params.feedbackType}`, flags);
+    if (response.feedback.suggestedSeverity) {
+        logLine(`Suggested severity: ${response.feedback.suggestedSeverity}`, flags);
+    }
+    if (response.feedback.dismissalReason) {
+        logLine(`Dismissal reason: ${response.feedback.dismissalReason}`, flags);
+    }
+    if (response.feedback.comment) {
+        logLine("Comment: saved", flags);
+    }
+    return payload;
+}
 export async function commandExportFindings(client, cwd, flags) {
     await ensureAuthenticated(client, flags);
     const binding = await requireWorkspaceBinding(cwd);

package/dist/findings.js

@@ -1,4 +1,8 @@
 import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js";
+import { ApiError } from "./api-client.js";
+const FINDING_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CANTINA_AUTH_TOKEN_ENV = "CANTINA_AUTH_TOKEN";
+const CANTINA_AUTH_TOKEN_ERROR = "Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` from a logged-in Cantina/Apex browser session. Export `CANTINA_AUTH_TOKEN` and retry.";
 function parsePositiveInt(value) {
     if (!value)
         return null;
@@ -8,6 +12,77 @@ function parsePositiveInt(value) {
     }
     return Math.floor(parsed);
 }
+async function parseWebRouteResponse(response) {
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+        return response.json().catch(() => null);
+    }
+    return response.text().catch(() => "");
+}
+function normalizeCantinaAuthToken(value) {
+    if (!value) {
+        return null;
+    }
+    let token = value.trim();
+    if (!token) {
+        return null;
+    }
+    if (token.toLowerCase().startsWith("auth_token=")) {
+        token = token.slice("auth_token=".length).trim();
+    }
+    return token.length > 0 ? token : null;
+}
+export function requireCantinaAuthToken() {
+    const token = normalizeCantinaAuthToken(process.env[CANTINA_AUTH_TOKEN_ENV]);
+    if (!token) {
+        throw new Error(CANTINA_AUTH_TOKEN_ERROR);
+    }
+    return token;
+}
+export function isFindingUuid(value) {
+    return FINDING_UUID_PATTERN.test(value.trim());
+}
+export function normalizeFindingRef(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    try {
+        const url = new URL(trimmed);
+        const segments = url.pathname.split("/").filter(Boolean);
+        return segments[segments.length - 1] ?? trimmed;
+    }
+    catch {
+        return trimmed;
+    }
+}
+function matchesFindingRef(finding, findingRef) {
+    const normalizedRef = findingRef.trim().toLowerCase();
+    return [finding.id, finding.findingIdentifier]
+        .filter((value) => typeof value === "string")
+        .some((value) => value.trim().toLowerCase() === normalizedRef);
+}
+async function requestFindingAppRoute(client, path, options = {}) {
+    const token = requireCantinaAuthToken();
+    const baseUrl = await client.getBaseUrl();
+    const headers = new Headers(options.headers ?? {});
+    // These routes still authenticate through the web app cookie, not Apex CLI bearer auth.
+    headers.set("Cookie", `auth_token=${token}`);
+    headers.set("Accept", "application/json");
+    if (options.json !== undefined) {
+        headers.set("Content-Type", "application/json");
+    }
+    const response = await fetch(new URL(path, baseUrl), {
+        ...options,
+        headers,
+        body: options.json !== undefined ? JSON.stringify(options.json) : options.body,
+    });
+    const body = await parseWebRouteResponse(response);
+    if (!response.ok) {
+        throw new ApiError(`Request failed with ${response.status}`, response.status, body);
+    }
+    return body;
+}
 export async function fetchScanFindings(client, scanId, limit) {
     const params = new URLSearchParams();
     const parsedLimit = parsePositiveInt(limit);
@@ -48,3 +123,60 @@ export async function resolveScanSelection(params) {
 export function describeScanSelection(scan) {
     return scan.scanUrl ?? getScanDisplayId(scan);
 }
+export async function resolveFindingSelection(params) {
+    const findingRef = normalizeFindingRef(params.requestedFindingRef);
+    if (!findingRef) {
+        throw new Error("A finding ID or finding identifier is required.");
+    }
+    if (isFindingUuid(findingRef)) {
+        return {
+            findingId: findingRef,
+            findingRef,
+            finding: null,
+            scan: null,
+            response: null,
+        };
+    }
+    if (!params.binding) {
+        throw new Error("A workspace binding is required to resolve finding identifiers. Bind this directory first or use the finding UUID directly.");
+    }
+    const scan = await resolveScanSelection({
+        client: params.client,
+        binding: params.binding,
+        requestedScanId: params.requestedScanId,
+    });
+    const response = await fetchScanFindings(params.client, scan.scanId, "1000");
+    const finding = response.findings.find((item) => matchesFindingRef(item, findingRef)) ?? null;
+    if (!finding) {
+        throw new Error(`Could not find finding "${findingRef}" in ${describeScanSelection(scan)}. Re-run with --scan to target a different scan, or use the finding UUID directly.`);
+    }
+    return {
+        findingId: finding.id,
+        findingRef,
+        finding,
+        scan,
+        response,
+    };
+}
+export async function createFindingComment(client, findingId, input) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/comments`, {
+        method: "POST",
+        json: {
+            content: input.content,
+            ...(input.parentCommentId ? { parentId: input.parentCommentId } : {}),
+        },
+    });
+}
+export async function submitFindingFeedback(client, findingId, input) {
+    return requestFindingAppRoute(client, `/api/findings/${encodeURIComponent(findingId)}/feedback`, {
+        method: "POST",
+        json: {
+            status: input.feedbackType,
+            ...(input.comment ? { comment: input.comment } : {}),
+            ...(input.suggestedSeverity
+                ? { suggestedSeverity: input.suggestedSeverity }
+                : {}),
+            ...(input.dismissalReason ? { dismissalReason: input.dismissalReason } : {}),
+        },
+    });
+}

package/dist/help.js

@@ -1,9 +1,13 @@
 export const CLI_HELP_TEXT = `Usage:
   apex                              Open the interactive Apex shell
-  apex credits                      Show scan credits for the active company
+  apex credits                      Show scan credits and audit scan entitlements for the active company
   apex scan                         Create or resolve a workspace for this directory and start a scan
   apex scans                        List scans for the current workspace binding
   apex findings                     List findings for the latest or selected scan
+  apex findings comment <finding-id|finding-identifier>
+                                    Add a comment or note to a finding
+  apex findings feedback <finding-id|finding-identifier> <valid|invalid>
+                                    Leave feedback; invalid requires --dismissal-reason
   apex export findings              Export findings for the latest or selected scan
   apex workspaces                   List accessible workspaces for the active company
   apex workspace                    Show the workspace currently bound to this directory
@@ -24,11 +28,19 @@ Flags:
   --company <id-or-handle>          Choose the Apex company to use
   --workspace-name <name>           Set the Apex workspace name for this directory
   --scan <scan-id>                  Select a specific scan for findings or export
+  --status valid|invalid            Set the finding feedback status explicitly
+  --content <markdown>              Supply comment content for apex findings comment
+  --comment <markdown>              Supply rationale for apex findings feedback
+  --parent-comment <comment-id>     Reply to an existing finding comment
+  --suggested-severity extreme|critical|high|medium|low|informational
+                                    Attach a suggested severity to valid feedback
+  --dismissal-reason false-positive|by-design|not-relevant
+                                    Explain why invalid feedback is being left
   --format markdown|json|gitlab-sast
                                     Choose the export format for findings
   --output <path>                   Write exported findings to this file path
   --limit <count>                   Limit the number of findings returned
-  --mode standard|ultra             Choose the scan mode
+  --mode standard|audit             Choose the scan mode
   --source-mode auto|remote|local   Control remote-vs-local source materialization
   --force                           Start a new scan even if another scan is active
   --repo <path>                     Include one or more explicit local source roots
@@ -39,17 +51,28 @@ Flags:
 
 Tips:
   apex scan uses the current directory name as the default workspace name unless you pass --workspace-name.
+  apex scan uses the current directory as the default source root unless you pass --repo.
+  audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
   apex workspace use accepts a workspace name, prefix, or ID.
+  Finding comments and feedback currently require CANTINA_AUTH_TOKEN from a logged-in Cantina/Apex browser session.
+  Invalid finding feedback requires --dismissal-reason.
+  Finding identifiers such as KERN2-25 resolve against the selected scan; pass --scan or use the finding UUID directly when needed.
   Quote workspace names that contain spaces:
     apex workspace use "Core Platform"
 `;
 export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common arguments.
 
 Commands:
-  /credits                Show scan credits for the active company
-  /scan [standard|ultra]  Start a new Apex scan for this workspace
+  /credits                Show scan credits and audit scan entitlements for the active company
+  /scan [standard|audit]  Start a new Apex scan for this workspace
   /scans                  List scans for this workspace
   /findings [scan-id]     List findings for the latest or selected scan
+  /findings comment <finding-ref> <comment>
+                          Add a comment or note to a finding
+  /findings feedback <finding-ref> valid [comment]
+                          Leave valid feedback on a finding
+  /findings feedback <finding-ref> invalid <reason> [comment]
+                          Leave invalid feedback; reason is false-positive, by-design, or not-relevant
   /export [scan-id]       Export findings for the latest or selected scan
   /workspaces             List accessible workspaces for the active company
   /cancel-scan [scan-id]  Cancel a running or most recent scan
@@ -70,6 +93,10 @@ Commands:
   /exit                   Exit Apex
 
 Tips:
+  audit is the user-facing name for the legacy ultra scan mode; ultra remains accepted as an alias.
   /workspace use accepts a workspace name, prefix, or ID.
+  /findings comment and /findings feedback require CANTINA_AUTH_TOKEN in the shell environment.
+  Invalid finding feedback requires a dismissal reason.
+  Use scripted CLI flags for advanced feedback options such as suggested severity or dismissal reason.
   Quote workspace names that contain spaces: /workspace use "Core Platform"
 `;

package/dist/mcp.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { z } from "zod";
 import { getMe, logout, startDeviceLogin, waitForDeviceLoginApproval } from "./auth.js";
 import { ApexApiClient, formatApiError } from "./api-client.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandScan, commandScans, commandStatus, commandWorkspace, commandWorkspaceUse, commandWorkspaces, } from "./commands.js";
 import { CLI_HELP_TEXT } from "./help.js";
 import { APEX_CLI_VERSION } from "./version.js";
 const MCP_WORKFLOW_GUIDE = `Use Apex through these tools instead of shelling out to the CLI.
@@ -15,10 +15,12 @@ Suggested workflow:
 3. Call apex-doctor for the target repository cwd.
 4. If the directory is not bound to the right workspace, call apex-workspaces and apex-workspace-use.
 5. Start and monitor scans with apex-scan, apex-status, apex-scans, apex-findings, and apex-export-findings.
+6. Leave finding comments or valid/invalid feedback with apex-finding-comment and apex-finding-feedback when review collaboration is needed.
 
 Notes:
 - Pass cwd explicitly for repository-specific operations.
 - Tool calls are always non-interactive and never auto-open a browser.
+- Use mode "audit" for audit scans; "ultra" remains accepted as a legacy alias.
 - Doctor reports whether Apex will use remote materialization or a local snapshot upload for each source.`;
 const WORKSPACE_BINDING_ERROR = "This directory is not bound to an Apex workspace yet. Run `apex workspaces` to list workspace names, prefixes, and IDs, then bind one with `apex workspace use \"<workspace name>\"`, or run `apex scan` to create or resolve one automatically.";
 const MISSING_PROVIDER_CONNECTIONS_ERROR = "Missing provider connections. Re-run interactively or pre-connect providers.";
@@ -248,7 +250,7 @@ function registerTools(server) {
     }, (value) => `Apex doctor completed for ${String(value.cwd)}.`));
     server.registerTool("apex-credits", {
         title: "Get Apex Credits",
-        description: "Show scan credits for the active or selected company.",
+        description: "Show scan credits and audit scan entitlements for the active or selected company.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
@@ -320,13 +322,13 @@ function registerTools(server) {
     }, (value) => `Bound ${String(value.cwd)} to an Apex workspace.`));
     server.registerTool("apex-scan", {
         title: "Start Apex Scan",
-        description: "Start a new Apex scan for any local repository or directory. Pass cwd explicitly for reliable workspace resolution.",
+        description: "Start a new Apex scan for the provided cwd by default. Pass repoPaths only to scan explicit alternate local roots. Use mode audit for audit scans.",
         inputSchema: {
             cwd: z.string().optional(),
             company: z.string().optional(),
             workspaceName: z.string().optional(),
             repoPaths: z.array(z.string()).optional(),
-            mode: z.enum(["standard", "ultra"]).optional(),
+            mode: z.enum(["standard", "audit", "ultra"]).optional(),
             sourceMode: z.enum(["auto", "remote", "local"]).optional(),
             force: z.boolean().optional(),
         },
@@ -417,6 +419,61 @@ function registerTools(server) {
             ...payload,
         };
     }, (value) => `Fetched Apex findings for ${String(value.cwd)}.`));
+    server.registerTool("apex-finding-comment", {
+        title: "Add Apex Finding Comment",
+        description: "Add a comment or note to an Apex finding. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            findingRef: z.string(),
+            content: z.string().min(1),
+            parentCommentId: z.string().optional(),
+            scanId: z.string().optional(),
+        },
+    }, async ({ cwd, findingRef, content, parentCommentId, scanId }) => runTool("apex-finding-comment", async () => {
+        const client = new ApexApiClient();
+        const targetCwd = resolveCwd(cwd);
+        const payload = await commandFindingComment(client, targetCwd, buildFlags({
+            scanId,
+        }), findingRef, content, parentCommentId);
+        return {
+            cwd: targetCwd,
+            ...payload,
+        };
+    }, (value) => `Added a finding comment for ${String(value.findingRef)}.`));
+    server.registerTool("apex-finding-feedback", {
+        title: "Leave Apex Finding Feedback",
+        description: "Leave valid or invalid feedback on an Apex finding. Requires CANTINA_AUTH_TOKEN in the MCP server environment.",
+        inputSchema: {
+            cwd: z.string().optional(),
+            findingRef: z.string(),
+            status: z.enum(["valid", "invalid"]),
+            comment: z.string().optional(),
+            suggestedSeverity: z
+                .enum(["extreme", "critical", "high", "medium", "low", "informational"])
+                .optional(),
+            dismissalReason: z
+                .enum(["false-positive", "by-design", "not-relevant"])
+                .optional(),
+            scanId: z.string().optional(),
+        },
+    }, async ({ cwd, findingRef, status, comment, suggestedSeverity, dismissalReason, scanId, }) => runTool("apex-finding-feedback", async () => {
+        const client = new ApexApiClient();
+        const targetCwd = resolveCwd(cwd);
+        const payload = await commandFindingFeedback(client, targetCwd, buildFlags({
+            scanId,
+        }), {
+            requestedFindingRef: findingRef,
+            feedbackType: status,
+            comment,
+            suggestedSeverity,
+            dismissalReason,
+        });
+        return {
+            cwd: targetCwd,
+            ...payload,
+        };
+    }, (value) => `Submitted ${String((value.feedback?.feedbackType ??
+        "finding"))} feedback for ${String(value.findingRef)}.`));
     server.registerTool("apex-export-findings", {
         title: "Export Apex Findings",
         description: "Export findings for the latest or selected Apex scan to a file on disk.",

package/dist/repo-discovery.js

@@ -1,37 +1,15 @@
 import { execFile } from "node:child_process";
-import { lstat, readdir, realpath } from "node:fs/promises";
+import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { extractCanonicalRepoMetadata } from "./repo-url.js";
 const execFileAsync = promisify(execFile);
-const IGNORED_DIRECTORIES = new Set([
-    ".git",
-    ".next",
-    "node_modules",
-    "dist",
-    "build",
-    "coverage",
-    ".turbo",
-    ".cache",
-    ".pnpm-store",
-    "tmp",
-    "vendor",
-]);
 async function runGit(cwd, args) {
     const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
         encoding: "utf8",
     });
     return stdout.trim();
 }
-async function isGitRepository(directory) {
-    try {
-        await runGit(directory, ["rev-parse", "--is-inside-work-tree"]);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 async function getGitTopLevel(directory) {
     try {
         const topLevel = await runGit(directory, ["rev-parse", "--show-toplevel"]);
@@ -103,25 +81,6 @@ function normalizeSelectedRoots(cwd, selectedPaths) {
     }
     return disjoint;
 }
-export async function findGitRepositoryRoots(cwd) {
-    const discovered = new Set();
-    async function walk(directory) {
-        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
-        const hasGitMarker = entries.some((entry) => entry.name === ".git");
-        if (hasGitMarker && (await isGitRepository(directory))) {
-            discovered.add(directory);
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            if (IGNORED_DIRECTORIES.has(entry.name))
-                continue;
-            await walk(path.join(directory, entry.name));
-        }
-    }
-    await walk(cwd);
-    return Array.from(discovered).sort((left, right) => left.length - right.length);
-}
 async function inspectGitRepository(rootCwd, directory) {
     const remoteUrl = await chooseRemote(directory);
     const metadata = remoteUrl ? extractCanonicalRepoMetadata(remoteUrl) : null;
@@ -163,7 +122,7 @@ async function inspectSource(rootCwd, requestedDirectory) {
 export async function discoverSources(cwd, selectedPaths = []) {
     const discoveredRoots = selectedPaths.length > 0
         ? normalizeSelectedRoots(cwd, selectedPaths)
-        : await findGitRepositoryRoots(cwd).then((gitRoots) => gitRoots.length > 0 ? gitRoots : [cwd]);
+        : [cwd];
     const sources = await Promise.all(discoveredRoots.map((root) => inspectSource(cwd, root)));
     sources.sort((left, right) => left.path.localeCompare(right.path));
     return { sources, scanned: discoveredRoots };

package/dist/scan.js

@@ -30,6 +30,10 @@ function readNumber(...values) {
     }
     return null;
 }
+function readScanMode(...values) {
+    const mode = readString(...values);
+    return mode === "ultra" ? "audit" : mode;
+}
 function getScanListItems(payload) {
     if (Array.isArray(payload)) {
         return payload;
@@ -63,7 +67,7 @@ function normalizeScanRecord(payload) {
         displayName: readString(record.displayName, record.display_name, record.name),
         sequenceNumber: readNumber(record.sequenceNumber, record.sequence_number),
         status: readString(record.status) ?? "unknown",
-        mode: readString(record.mode, record.scanType, record.scan_type),
+        mode: readScanMode(record.mode, record.scanType, record.scan_type),
         scanUrl: readString(record.scanUrl, record.url, record.scan_url),
         createdAt: readTimestamp(record, "createdAt", "created_at"),
         startedAt: readTimestamp(record, "startedAt", "started_at"),

package/dist/session.js

@@ -70,6 +70,52 @@ function getSourceMode(flags) {
     const value = getFlagString(flags, "source-mode");
     return value === "remote" || value === "local" ? value : "auto";
 }
+function buildFallbackLocalArchivePlan(source, sourceMode) {
+    const reason = sourceMode === "local"
+        ? "user_requested_local_snapshot"
+        : source.kind === "directory_candidate"
+            ? "non_git_directory"
+            : source.dirty
+                ? "dirty_worktree"
+                : source.repoUrl
+                    ? "remote_access_unavailable"
+                    : "missing_remote";
+    return {
+        path: source.path,
+        displayName: source.displayName,
+        relativePath: source.path,
+        sourceKind: "local_archive",
+        archiveRequired: true,
+        reason,
+        git: source.kind === "git_candidate"
+            ? {
+                repoUrl: source.repoUrl,
+                provider: source.provider,
+                branch: source.branch,
+                commitSha: source.commitSha,
+                dirty: source.dirty,
+            }
+            : {
+                repoUrl: null,
+                provider: null,
+                branch: null,
+                commitSha: null,
+                dirty: false,
+            },
+    };
+}
+function ensurePlannedSources(selection, resolve) {
+    if (resolve.plannedSources.length > 0) {
+        return resolve;
+    }
+    if (selection.sourceMode === "remote") {
+        throw new Error("Workspace resolution did not return any remote scan sources.");
+    }
+    return {
+        ...resolve,
+        plannedSources: selection.sources.map((source) => buildFallbackLocalArchivePlan(source, selection.sourceMode)),
+    };
+}
 export async function ensureAuthenticated(client, flags) {
     return login(client, {
         noOpen: flags["no-open"] === true,
@@ -99,7 +145,7 @@ export async function selectWorkspaceTarget(cwd, me, flags) {
     };
 }
 export async function resolveWorkspaceSelection(client, selection) {
-    const resolve = await client.request("/api/cli/v2/local-workspaces/resolve", {
+    const rawResolve = await client.request("/api/cli/v2/local-workspaces/resolve", {
         method: "POST",
         json: {
             companyId: selection.company.id,
@@ -124,6 +170,7 @@ export async function resolveWorkspaceSelection(client, selection) {
                 }),
         },
     });
+    const resolve = ensurePlannedSources(selection, rawResolve);
     return {
         company: selection.company,
         workspaceName: selection.workspaceName,

package/dist/shell.js

@@ -1,14 +1,14 @@
 import { SHELL_HELP_TEXT } from "./help.js";
-import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
+import { commandCancelScan, commandConnect, commandCredits, commandDoctor, commandExportFindings, commandFindingComment, commandFindingFeedback, commandFindings, commandLogout, commandScan, commandScans, commandStatus, commandUpdate, commandWorkspace, commandWorkspaceUse, commandWorkspaces, initializeInteractiveSession, openCurrentApexView, } from "./commands.js";
 import { withFlag } from "./args.js";
 import { printCompanyDetails, printInteractiveSessionSummary, printSourceList, printWorkspaceDetails, } from "./output.js";
 import { readLine } from "./prompt.js";
 import { formatApiError } from "./api-client.js";
 const SHELL_COMPLETIONS = [
     { command: "credits" },
-    { command: "scan", args: ["standard", "ultra"] },
+    { command: "scan", args: ["standard", "audit", "ultra"] },
     { command: "scans" },
-    { command: "findings" },
+    { command: "findings", args: ["comment", "feedback"] },
     { command: "export" },
     { command: "workspaces" },
     { command: "cancel-scan" },
@@ -178,8 +178,8 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             return {};
         case "scan": {
             const mode = parsed.args[0];
-            if (mode && !["standard", "ultra"].includes(mode)) {
-                process.stderr.write("Usage: /scan [standard|ultra]\n");
+            if (mode && !["standard", "audit", "ultra"].includes(mode)) {
+                process.stderr.write("Usage: /scan [standard|audit|ultra]\n");
                 return {};
             }
             const result = await commandScan(client, cwd, mode ? withFlag(shellFlags, "mode", mode) : shellFlags);
@@ -200,6 +200,43 @@ async function runShellCommand(client, cwd, parsed, shellFlags, session) {
             await commandScans(client, cwd, shellFlags);
             return {};
         case "findings": {
+            if (parsed.args[0] === "comment") {
+                if (parsed.args.length < 3) {
+                    process.stderr.write("Usage: /findings comment <finding-id|finding-identifier> <comment>\n");
+                    return {};
+                }
+                await commandFindingComment(client, cwd, shellFlags, parsed.args[1], parsed.args.slice(2).join(" "));
+                return {};
+            }
+            if (parsed.args[0] === "feedback") {
+                const findingRef = parsed.args[1];
+                const feedbackType = parsed.args[2];
+                if (!findingRef ||
+                    (feedbackType !== "valid" && feedbackType !== "invalid")) {
+                    process.stderr.write("Usage: /findings feedback <finding-id|finding-identifier> <valid|invalid> [comment]\n");
+                    return {};
+                }
+                const dismissalReason = feedbackType === "invalid" ? parsed.args[3] : null;
+                if (feedbackType === "invalid" &&
+                    !["false-positive", "by-design", "not-relevant"].includes(dismissalReason ?? "")) {
+                    process.stderr.write("Usage: /findings feedback <finding-id|finding-identifier> invalid <false-positive|by-design|not-relevant> [comment]\n");
+                    return {};
+                }
+                await commandFindingFeedback(client, cwd, shellFlags, {
+                    requestedFindingRef: findingRef,
+                    feedbackType,
+                    comment: parsed.args
+                        .slice(feedbackType === "invalid" ? 4 : 3)
+                        .join(" ")
+                        .trim() || null,
+                    ...(dismissalReason
+                        ? {
+                            dismissalReason: dismissalReason,
+                        }
+                        : {}),
+                });
+                return {};
+            }
             if (parsed.args.length > 1) {
                 process.stderr.write("Usage: /findings [scan-id]\n");
                 return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cantinasecurity/apex-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Standalone CLI and MCP server for Apex.",
   "private": false,
   "type": "module",

package/skills/apex-cli/SKILL.md

@@ -17,13 +17,20 @@ Workflow:
 4. Call `apex-doctor` before starting a scan if workspace binding or source planning might be unclear.
 5. If the directory is not bound to the right workspace, call `apex-workspaces` and `apex-workspace-use`.
 6. Use `apex-scan`, `apex-status`, `apex-scans`, `apex-findings`, and `apex-export-findings` for the scan lifecycle.
+7. Use `apex-finding-comment` and `apex-finding-feedback` when the user wants to leave review notes or valid/invalid feedback on a finding.
 
 Guidelines:
 
 - Do not rely on interactive CLI prompts. The MCP tools are intentionally non-interactive.
+- `apex-credits` reports standard credits and audit scan entitlements when Bedrock returns both balances.
+- `apex-scan` scans the provided `cwd` by default; pass `repoPaths` only when the user asks to scan explicit alternate roots.
 - `apex-doctor` reports whether Apex will use remote materialization or a local snapshot upload for each selected source.
 - Apex can scan plain local directories and dirty git worktrees without provider connections by using local snapshot uploads.
+- Audit scans use `mode: "audit"` in user-facing instructions. The legacy `ultra` mode remains accepted as an alias, but audit scans still require provider-backed GitHub or GitLab sources.
 - `apex-workspace-use` accepts a workspace name, prefix, or ID.
 - Use `sourceMode: "remote"` only when the user explicitly wants to forbid local snapshot fallbacks.
 - Use `force: true` on `apex-scan` only when the user explicitly wants to replace or overlap an active scan.
 - Prefer `apex-findings` for quick inspection and `apex-export-findings` when the user needs a file artifact.
+- Finding comments and feedback currently require `CANTINA_AUTH_TOKEN` in the MCP server environment because those writes go through the Cantina web-app routes instead of the Apex CLI bearer-token routes.
+- Invalid finding feedback requires `dismissalReason`; valid feedback can include `suggestedSeverity`, including `extreme`.
+- Finding identifiers such as `KERN2-25` resolve against the selected or latest scan for the current workspace binding. Pass an explicit scan when needed, or use the finding UUID directly.