featureparity 0.0.21 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ae3f4be081207da9feb300fbdfaad6d2afddf2ffb021ffc8136508da964f0c2
-  data.tar.gz: 74d2cf3feb18ea77cac72f38be15c5eb6870d237d76f2a21a3b859853649b02d
+  metadata.gz: b06053deae8d893e793e13d2dd56773db5ff1ce04d2cc5f2be40b65da3520d11
+  data.tar.gz: 0c7d0b2ae20e481fedab84bf188d7a3b8c3ae47d91c0b16c816d49e697d2f16a
 SHA512:
-  metadata.gz: f14f50d9f5e6d620341081a55ee98734bafd6893ade078cb424246c6ddb16a2f85a8aff6b5d28dc1d969505708b0e59806628699c47146736b024f90c0e0c6e6
-  data.tar.gz: 156d5c4e679017b8d5ec7825eb51d7eb64acec51daf02700a263f58e20251c2136efadab399244856f4ce943fe832825e89e45a75f57a814368e8dbc54a5189e
+  metadata.gz: b8f6ae3cedd0abb1c6a1cc248092d83f1643858d08aee76bd4d6707f1a5072bbc1f06d0ba83ed35cc79cd36afd24b543e625d58c6f9044c102f47b77a4cc2d79
+  data.tar.gz: c938e91cd9bbf92197bb0a85dcb6488d0c0621ed6760f12bdac0e4c23002bac09ca7232d3a12d93618011261d90150f98a02dc861e0f2b893bc8ac9f003d0b10

data/lib/fp/cli.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Fp
   # Main CLI entry point - parses global flags and dispatches to commands
   class CLI
@@ -7,6 +9,7 @@ module Fp
       'init' => Commands::Init,
       'projects' => Commands::Projects,
       'surfaces' => Commands::Surfaces,
+      'showroom' => Commands::Showroom,
       'list' => Commands::List,
       'show' => Commands::Show,
       'propose' => Commands::Propose,
@@ -39,6 +42,12 @@ module Fp
         global_opts = extract_global_options(args)
 
         command_name = args.shift || 'help'
+
+        # `fp --version` / `fp -v` are aliases for `fp version` (Fizzy #1489 ask 3).
+        # A bare version flag is the universal expectation for a CLI; without this it
+        # reported "Unknown command: --version".
+        command_name = 'version' if %w[--version -v].include?(command_name)
+
         command_class = COMMANDS[command_name]
 
         unless command_class
@@ -48,6 +57,15 @@ module Fp
           exit 1
         end
 
+        # Per-command help (Fizzy #1489): `fp <cmd> --help` / `fp <cmd> -h` prints the
+        # command's own usage and flags instead of running it. Detected here, before
+        # auth, so `fp report --help` works with no API key — the whole point is to let
+        # someone discover a command's flags before they can run it.
+        if wants_help?(args)
+          print_command_help(command_name, command_class, json: global_opts[:json])
+          return
+        end
+
         # Profile/config commands don't need auth. `init` is here too: it only writes
         # files into the repo, and onboarding a repo must work before anyone has a key.
         needs_auth = !%w[init profile config repos setup whoami version help].include?(command_name)
@@ -78,6 +96,28 @@ module Fp
 
       private
 
+      # True when the remaining args ask for help on the command: `--help` or `-h`
+      # anywhere in the args. We don't treat a lone `help` positional specially here —
+      # that's a real subcommand for some commands.
+      def wants_help?(args)
+        args.include?('--help') || args.include?('-h')
+      end
+
+      # Print a command's own help page. `fp help <cmd>` routes here too, via the Help
+      # command. Commands that haven't adopted the help DSL still get a usable page
+      # (summary falls back to a generic line, flags to the global set).
+      #
+      # With --json, emit the command's flag schema instead of the human page (Fizzy
+      # #1489 ask 4) so an agent or the skill can read a command's flags, required-ness,
+      # and usage straight from the gem rather than scraping KNOWN_FLAGS.
+      def print_command_help(command_name, command_class, json: false)
+        if json
+          puts JSON.pretty_generate(command_class.help_schema(command_name))
+        else
+          puts command_class.help_text(command_name)
+        end
+      end
+
       def extract_global_options(args)
         opts = { json: false, profile: nil, api_url: nil }
 

data/lib/fp/client.rb

@@ -82,6 +82,20 @@ module Fp
       delete("/api/projects/#{project_id}/surfaces/#{surface_id}")
     end
 
+    # GET /projects/:id/showroom
+    # The client showroom as a client would see it (Fizzy #1479). Open to the team and
+    # their agents; the response carries only what a client is shown.
+    def get_showroom(project_id)
+      get("/api/projects/#{project_id}/showroom")
+    end
+
+    # GET /projects/:id/showroom/share_link
+    # The share link, or null when sharing is off. Humans only: an agent's key gets 403,
+    # which `fp showroom` reports as "unknown" rather than treating as an error.
+    def get_showroom_share_link(project_id)
+      get("/api/projects/#{project_id}/showroom/share_link")
+    end
+
     # GET /requirements
     def list_requirements(project_id: nil, status: nil, category: nil, tag: nil)
       params = {}
@@ -179,6 +193,16 @@ module Fp
       post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
     end
 
+    # DELETE /requirements/:id/changes/:change_id
+    #
+    # Withdraw an open proposal. Only the proposal's author can withdraw it; the
+    # requirement is restored to what it was before the proposal (the same rollback a
+    # reject performs). This is how an agent *amends* a proposal under the one-open-
+    # proposal rule: withdraw, then propose again.
+    def withdraw_requirement_change(requirement_id, change_id)
+      delete("/api/requirements/#{requirement_id}/changes/#{change_id}")
+    end
+
     # GET /projects/:project_id/evidence — the receipts already filed for a project,
     # optionally narrowed to one requirement slug and/or surface.
     def list_evidence(project_id, slug: nil, surface: nil)

data/lib/fp/commands/analyze.rb

@@ -15,6 +15,16 @@ module Fp
     # put dozens of requirements up for review at once. The report says what *kind* of
     # follow-up each finding suggests; a human picks which proposals get filed.
     class Analyze < Base
+      help_summary 'Triage requirement quality (read-only; never proposes or files anything)'
+      help_usage 'fp analyze [<slug>] --project <slug> [--status S] [--conflicts] [--cached]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :status, 'Limit to requirements with this status'
+      help_flag :conflicts, 'Include cross-requirement conflict findings'
+      help_flag :force, 'Re-analyze even cached (unchanged) requirements'
+      help_flag :cached, 'Read cached analyses only; do not spend model calls'
+      help_example 'fp analyze --project stowzilla'
+      help_example 'fp analyze print_container_qr --project stowzilla --conflicts'
+
       KNOWN_FLAGS = {
         project: :string,
         status: :string,

data/lib/fp/commands/attach.rb

@@ -6,6 +6,22 @@ module Fp
   module Commands
     # Upload visual test evidence or another supporting file to a requirement.
     class Attach < Base
+      help_summary 'Upload screenshot/video/file evidence to a requirement (rm to delete)'
+      help_usage 'fp attach <slug> <file> --project <slug> --surface <surface> [flags]',
+                 'fp attach rm <slug> <attachment-id> --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Surface the capture is for (required for images/videos)'
+      help_flag :captured_at, 'ISO8601 timestamp the capture was taken'
+      help_flag :deployed_at, 'ISO8601 timestamp of the deployment the capture observed'
+      help_flag :deployment_url, 'URL of the deployment under test'
+      help_flag :test_run_url, 'CI run / test-run URL'
+      help_flag :sha, 'Commit SHA the capture observed'
+      help_flag :example_title, 'Name of the individual test this media proves'
+      help_flag :evidence_key, 'Composite receipt key (surface:repo:test_type) to bind to'
+      help_example 'fp attach print_qr e2e-run.webm --project stowzilla --surface customer_web --example-title "prints a QR code onto the container label"'
+      help_example 'fp attach rm print_qr <attachment-id> --project stowzilla'
+      help_note 'Visual: png, jpg, gif, webp, mp4, webm, mov. Text/docs: txt, md, json, svg, pdf. Max 100 MB.'
+
       CONTENT_TYPES = {
         'png' => 'image/png', 'jpg' => 'image/jpeg', 'jpeg' => 'image/jpeg',
         'gif' => 'image/gif', 'webp' => 'image/webp', 'svg' => 'image/svg+xml',
@@ -31,58 +47,88 @@ module Fp
         opts, positional = parse_flags(args, KNOWN_FLAGS)
         return delete_attachment(opts, positional.drop(1)) if %w[rm delete].include?(positional.first)
 
-        upload_attachment(opts, positional)
+        upload_attachments(opts, positional)
       end
 
       private
 
-      def upload_attachment(opts, positional)
-        slug, file_path = positional
+      # fp attach <slug> <file> [<file> ...]
+      # Several files attach in one command: each is uploaded to the same requirement with
+      # the shared flags (surface, bound test, deployment context). A failure on one file
+      # doesn't abort the rest, and the exit status reflects whether every upload succeeded.
+      def upload_attachments(opts, positional)
+        slug = positional.first
+        file_paths = positional.drop(1)
         return usage_error('Missing requirement slug') if slug.to_s.empty?
-        return usage_error('Missing file path') if file_path.to_s.empty?
-        return command_error("File not found: #{file_path}") unless File.file?(file_path)
+        return usage_error('Missing file path') if file_paths.empty?
+
+        # Validate every file up front and resolve the requirement once, so a bad path in a
+        # batch is reported before any upload begins and all files share one lookup.
+        prepared = file_paths.map { |path| prepare_file(path, opts) }
+        invalid = prepared.find { |p| p[:error] }
+        return command_error(invalid[:error]) if invalid
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        requirement_result = client.find_requirement_by_slug(project_id, slug)
+        return api_error(requirement_result) unless requirement_result[:ok]
+
+        requirement_id = requirement_result[:data].dig('requirement', 'id')
+
+        results = prepared.map { |file| upload_one(requirement_id, slug, file, opts) }
+        report_batch(results, slug)
+      end
+
+      # Validate a single file and compute its upload metadata. Returns a hash carrying
+      # either an :error string or the resolved filename/extension/content_type/size.
+      def prepare_file(file_path, opts)
+        return { error: "File not found: #{file_path}" } unless File.file?(file_path)
 
         filename = File.basename(file_path)
         extension = File.extname(filename).delete('.').downcase
         content_type = CONTENT_TYPES[extension]
         unless content_type
-          return command_error("Unsupported file type: .#{extension}. Allowed: #{CONTENT_TYPES.keys.join(', ')}")
+          return { error: "Unsupported file type: .#{extension}. Allowed: #{CONTENT_TYPES.keys.join(', ')}" }
         end
 
         size = File.size(file_path)
-        return command_error("File is empty: #{file_path}") if size.zero?
+        return { error: "File is empty: #{file_path}" } if size.zero?
         if size > MAX_FILE_SIZE
-          return command_error("File too large: #{format_size(size)} (max #{format_size(MAX_FILE_SIZE)})")
+          return { error: "File too large: #{format_size(size)} (max #{format_size(MAX_FILE_SIZE)})" }
         end
         if VISUAL_EXTENSIONS.include?(extension) && opts[:surface].to_s.empty?
-          return command_error('--surface is required for screenshot and video evidence')
+          return { error: '--surface is required for screenshot and video evidence' }
         end
 
-        require_project!(opts)
-        project_id = resolve_project_id(opts[:project])
-        requirement_result = client.find_requirement_by_slug(project_id, slug)
-        return api_error(requirement_result) unless requirement_result[:ok]
+        { path: file_path, filename: filename, extension: extension, content_type: content_type, size: size }
+      end
 
-        requirement_id = requirement_result[:data].dig('requirement', 'id')
+      # Upload one prepared file. Returns { ok:, filename:, attachment: } or
+      # { ok: false, filename:, error: } so the batch can report per-file outcomes.
+      def upload_one(requirement_id, slug, file, opts)
         presign_result = client.presign_attachment(
           requirement_id,
-          filename: filename,
-          content_type: content_type,
-          size_bytes: size
+          filename: file[:filename],
+          content_type: file[:content_type],
+          size_bytes: file[:size]
         )
-        return api_error(presign_result, prefix: 'Failed to get upload URL') unless presign_result[:ok]
+        unless presign_result[:ok]
+          return { ok: false, filename: file[:filename], error: error_text(presign_result, 'Failed to get upload URL') }
+        end
 
         presign = presign_result[:data]['presign']
-        upload_result = client.upload_to_presigned_url(presign['upload_url'], file_path, content_type)
-        return api_error(upload_result, prefix: 'Upload failed') unless upload_result[:ok]
+        upload_result = client.upload_to_presigned_url(presign['upload_url'], file[:path], file[:content_type])
+        unless upload_result[:ok]
+          return { ok: false, filename: file[:filename], error: error_text(upload_result, 'Upload failed') }
+        end
 
         create_result = client.create_attachment(
           requirement_id,
           attachment_id: presign['attachment_id'],
           s3_key: presign['s3_key'],
-          filename: filename,
-          content_type: content_type,
-          size_bytes: size,
+          filename: file[:filename],
+          content_type: file[:content_type],
+          size_bytes: file[:size],
           surface: opts[:surface],
           captured_at: opts[:captured_at],
           deployed_at: opts[:deployed_at],
@@ -92,20 +138,41 @@ module Fp
           example_title: opts[:example_title],
           evidence_key: opts[:evidence_key]
         )
-        return api_error(create_result, prefix: 'Failed to confirm upload') unless create_result[:ok]
-
-        attachment = create_result[:data]['attachment']
-        output.success({ attachment: attachment }) do
-          puts "Uploaded #{filename} to requirement '#{slug}'."
-          puts "  ID:           #{attachment['id']}"
-          puts "  Surface:      #{attachment['surface']}" if attachment['surface']
-          puts "  Test:         #{attachment['example_title']}" if attachment['example_title']
-          puts "  Evidence key: #{attachment['evidence_key']}" if attachment['evidence_key']
-          puts "  Captured:     #{attachment['captured_at']}" if attachment['captured_at']
-          puts "  Deploy:       #{attachment['deployment_url']}" if attachment['deployment_url']
-          puts '  Deployment context: unknown' if VISUAL_EXTENSIONS.include?(extension) && attachment['deployed_at'].to_s.empty?
+        unless create_result[:ok]
+          return { ok: false, filename: file[:filename], error: error_text(create_result, 'Failed to confirm upload') }
+        end
+
+        { ok: true, filename: file[:filename], extension: file[:extension], attachment: create_result[:data]['attachment'] }
+      end
+
+      def report_batch(results, slug)
+        uploaded = results.select { |r| r[:ok] }
+        failed = results.reject { |r| r[:ok] }
+
+        output.success({ slug: slug, uploaded: uploaded.map { |r| r[:attachment] }, failed: failed.map { |r| { filename: r[:filename], error: r[:error] } } }) do
+          uploaded.each { |r| print_uploaded(r, slug) }
+          failed.each { |r| $stderr.puts "Failed: #{r[:filename]}: #{r[:error]}" }
+          if results.length > 1
+            puts
+            puts "#{uploaded.length} of #{results.length} file(s) uploaded to requirement '#{slug}'."
+          end
+        end
+
+        failed.empty? ? 0 : 1
+      end
+
+      def print_uploaded(result, slug)
+        attachment = result[:attachment]
+        puts "Uploaded #{result[:filename]} to requirement '#{slug}'."
+        puts "  ID:           #{attachment['id']}"
+        puts "  Surface:      #{attachment['surface']}" if attachment['surface']
+        puts "  Test:         #{attachment['example_title']}" if attachment['example_title']
+        puts "  Evidence key: #{attachment['evidence_key']}" if attachment['evidence_key']
+        puts "  Captured:     #{attachment['captured_at']}" if attachment['captured_at']
+        puts "  Deploy:       #{attachment['deployment_url']}" if attachment['deployment_url']
+        if VISUAL_EXTENSIONS.include?(result[:extension]) && attachment['deployed_at'].to_s.empty?
+          puts '  Deployment context: unknown'
         end
-        0
       end
 
       def delete_attachment(opts, positional)
@@ -128,16 +195,19 @@ module Fp
 
       def usage_error(message, delete: false)
         usage = delete ? 'fp attach rm <slug> <id> [--project <project>]' :
-                         'fp attach <slug> <file> [--surface <surface>] [--project <project>]'
+                         'fp attach <slug> <file> [<file> ...] [--surface <surface>] [--project <project>]'
         command_error("#{message}. Usage: #{usage}")
       end
 
       def api_error(result, prefix: nil)
-        message = [prefix, result[:error]].compact.join(': ')
-        output.error(message, status: result[:status])
+        output.error(error_text(result, prefix), status: result[:status])
         1
       end
 
+      def error_text(result, prefix = nil)
+        [prefix, result[:error]].compact.join(': ')
+      end
+
       def command_error(message)
         output.error(message)
         1

data/lib/fp/commands/attachments.rb

@@ -6,6 +6,12 @@ module Fp
   module Commands
     # List a requirement's attachments, or get a short-lived URL for one.
     class Attachments < Base
+      help_summary "List a requirement's attachments, or get a download URL for one"
+      help_usage 'fp attachments <slug> --project <slug>',
+                 'fp attachments <slug> <attachment-id> --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_example 'fp attachments print_container_qr --project stowzilla'
+
       KNOWN_FLAGS = { project: :string }.freeze
 
       def run(args)

data/lib/fp/commands/base.rb

@@ -4,6 +4,142 @@ module Fp
   module Commands
     # Base class for all commands
     class Base
+      # --- Per-command help (Fizzy #1489) -------------------------------------
+      #
+      # Every command declares its own usage, a one-line summary, its flags, and a
+      # few examples here, so `fp <cmd> --help`, `fp <cmd> -h`, and `fp help <cmd>`
+      # can all print them. Before this, a command's flags were only discoverable by
+      # reading KNOWN_FLAGS in the gem — `fp report --help` just ran `fp report` and
+      # failed validation.
+      #
+      # This is a small declarative DSL rather than a scrape of KNOWN_FLAGS on
+      # purpose: the flag constants are named inconsistently across commands
+      # (KNOWN_FLAGS, ADD_FLAGS, CREATE_FLAGS, FIELD_FLAGS...), some commands take
+      # positional subcommands with no constant at all, and — most importantly — a
+      # bare list of flag *names* barely improves on "read the gem". The value an
+      # agent needs is what each flag means and which are required, which only a
+      # written description carries.
+      class << self
+        # A one-line description shown in `fp help` and at the top of per-command help.
+        def help_summary(text = nil)
+          @help_summary = text if text
+          @help_summary
+        end
+
+        # One or more usage lines, e.g. "fp report <slug> --project <slug> --surface X".
+        def help_usage(*lines)
+          @help_usage ||= []
+          @help_usage.concat(lines.flatten) unless lines.empty?
+          @help_usage
+        end
+
+        # Declare a flag: name (symbol or string), a description, and whether it's
+        # required. Order of declaration is the order shown.
+        def help_flag(name, description, required: false)
+          @help_flags ||= []
+          @help_flags << { name: name.to_s.tr('_', '-'), description: description, required: required }
+        end
+
+        def help_flags
+          @help_flags ||= []
+        end
+
+        # Example invocations, each an array [command_line, optional_comment].
+        def help_example(command_line, comment = nil)
+          @help_examples ||= []
+          @help_examples << { command: command_line, comment: comment }
+        end
+
+        def help_examples
+          @help_examples ||= []
+        end
+
+        # A short free-form note shown after the flags (caveats, related commands).
+        def help_note(text = nil)
+          @help_note = text if text
+          @help_note
+        end
+
+        # True when a command has opted into the help DSL. Commands that haven't
+        # still get a generic help page listing global flags.
+        def help_defined?
+          !help_summary.nil? || !help_usage.empty? || !help_flags.empty?
+        end
+
+        # Render the full help page for this command.
+        #   command_name - the dispatch name (e.g. "ci-report"), so usage lines and
+        #                  the header match what the user typed.
+        def help_text(command_name)
+          lines = []
+          lines << "fp #{command_name} - #{help_summary}" if help_summary
+          lines << '' unless lines.empty?
+
+          usage = help_usage.empty? ? ["fp #{command_name} [flags]"] : help_usage
+          lines << 'USAGE'
+          usage.each { |u| lines << "  #{u}" }
+
+          unless help_flags.empty?
+            lines << ''
+            lines << 'FLAGS'
+            width = help_flags.map { |f| f[:name].length }.max
+            help_flags.each do |f|
+              label = "--#{f[:name].ljust(width)}"
+              req = f[:required] ? ' (required)' : ''
+              lines << "  #{label}  #{f[:description]}#{req}"
+            end
+          end
+
+          lines << ''
+          lines << 'GLOBAL FLAGS'
+          lines << '  --json            Output as a JSON envelope'
+          lines << '  --profile <name>  Use a named profile (-p for short)'
+          lines << '  --api-url <url>   Override the API URL for this command'
+
+          unless help_examples.empty?
+            lines << ''
+            lines << 'EXAMPLES'
+            help_examples.each do |ex|
+              lines << "  # #{ex[:comment]}" if ex[:comment]
+              lines << "  #{ex[:command]}"
+            end
+          end
+
+          if help_note
+            lines << ''
+            help_note.each_line { |l| lines << "  #{l.chomp}" }
+          end
+
+          lines.join("\n")
+        end
+
+        # The command's flag schema as a plain hash (Fizzy #1489 ask 4). `--json` on a
+        # help invocation emits this, so agents and the Agent Skills package can read a
+        # command's real flags — names, descriptions, required-ness, usage, examples —
+        # straight from the installed gem and stay in sync with it automatically.
+        #
+        # Global flags are reported separately from the command's own so a consumer can
+        # tell "every command accepts --json" from "this command accepts --surface".
+        def help_schema(command_name)
+          {
+            'command' => command_name,
+            'summary' => help_summary,
+            'usage' => (help_usage.empty? ? ["fp #{command_name} [flags]"] : help_usage),
+            'flags' => help_flags.map do |f|
+              { 'name' => f[:name], 'description' => f[:description], 'required' => f[:required] }
+            end,
+            'global_flags' => [
+              { 'name' => 'json', 'description' => 'Output as a JSON envelope', 'required' => false },
+              { 'name' => 'profile', 'description' => 'Use a named profile (-p for short)', 'required' => false },
+              { 'name' => 'api-url', 'description' => 'Override the API URL for this command', 'required' => false }
+            ],
+            'examples' => help_examples.map do |ex|
+              { 'command' => ex[:command], 'comment' => ex[:comment] }
+            end,
+            'note' => help_note
+          }
+        end
+      end
+
       def initialize(client: nil, output: nil, config: nil)
         @client = client
         @output = output

data/lib/fp/commands/changed_tests.rb

@@ -6,6 +6,18 @@ module Fp
     # exact candidate fingerprint.
     class ChangedTests < Base
       CLASSIFICATIONS = %w[still_proves no_longer_proves uncertain].freeze
+
+      help_summary 'List CI-detected revisions to bound tests, and assess a candidate'
+      help_usage 'fp changed-tests [--json]',
+                 'fp changed-tests assess <finding-id> --candidate-fingerprint <sha256> --classification C --explanation "..."'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Limit to one surface'
+      help_flag :test_type, 'Limit to one test type'
+      help_flag :classification, "Assessment: #{CLASSIFICATIONS.join(', ')}"
+      help_flag :explanation, 'Plain-language reason for the assessment'
+      help_flag :candidate_fingerprint, 'The exact SHA-256 being assessed'
+      help_example 'fp changed-tests'
+      help_example 'fp changed-tests assess abc123 --candidate-fingerprint <sha> --classification still_proves --explanation "Same result asserted"'
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,

data/lib/fp/commands/changes.rb

@@ -11,6 +11,15 @@ module Fp
     # Actions it can discover source URLs from the pull request body, append a job
     # summary, and keep a managed table in the pull request description itself.
     class Changes < Base
+      help_summary 'Show (or publish to a PR) requirement activity linked to a work item'
+      help_usage 'fp changes [--source-url URL]... [--github-pr] [--github-summary]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :source_url, 'Work-item URL to match (repeatable; auto-discovered in a PR body otherwise)'
+      help_flag :github_pr, "Write a managed table into the pull request's description"
+      help_flag :github_summary, "Append the table to the GitHub Actions job summary"
+      help_example 'fp changes --source-url https://app.fizzy.do/123/cards/456'
+      help_example 'fp changes --github-pr --github-summary', 'In CI: keep a linked table in the PR'
+
       PR_SECTION_BEGIN = '<!-- feature-parity:requirement-changes:begin -->'
       PR_SECTION_END = '<!-- feature-parity:requirement-changes:end -->'
 

data/lib/fp/commands/check.rb

@@ -36,6 +36,21 @@ module Fp
     # one. Prefer setting the project's level to `regression` over living on --warn-only
     # forever, since a warn-only gate is one nobody reads.
     class Check < Base
+      help_summary 'Enforce parity; exits non-zero when the project violates its level'
+      help_usage 'fp check [--project <slug>] [--surface X] [--level L] [--junit FILE]... [--warn-only]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Gate a single surface'
+      help_flag :test_type, 'Gate a single test type'
+      help_flag :level, 'Override the enforcement level for this run (off/regression/covered/strict)'
+      help_flag :junit, "Gate the branch on this run's results, overlaid on the grid (repeatable, one per surface)"
+      help_flag :base_dir, "Where the report's relative test-file paths resolve from"
+      help_flag :warn_only, 'Report violations but still exit 0'
+      help_example 'fp check', 'Gate on recorded state (project from .featureparity.yml)'
+      help_example 'fp check --surface api --junit junit.xml', "Gate a PR branch on its own results"
+      help_example 'fp check --warn-only --json'
+      help_note "Exit 0 = passed, 1 = violations (or request failed). The level lives on the project\n" \
+                'server-side; --level only overrides this one run.'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
@@ -182,11 +197,12 @@ module Fp
           end
 
           print_state_counts(summary)
+          print_scope_notice(report)
           print_violations(violations)
           print_orphans(report)
           print_pending_reviews(report, project_slug)
           print_unscoped_warning(summary, project_slug)
-          print_verdict(passed, violations, opts)
+          print_verdict(passed, violations, opts, report)
         end
       end
 
@@ -198,6 +214,24 @@ module Fp
         puts
       end
 
+      # A surface-scoped run (--surface, or a single `surface:` in .featureparity.yml)
+      # only measures the one surface it was given. That's correct for a per-surface CI
+      # job, but it means the verdict covers a slice of the project — so a bare "Gate
+      # passed" would read as "the whole project is in parity" when other required
+      # surfaces were never looked at (Fizzy #1490). Name them up front, and the verdict
+      # line qualifies itself to match.
+      def print_scope_notice(report)
+        return unless report['scoped']
+
+        excluded = report['scoped_out_surfaces'] || []
+        return if excluded.empty?
+
+        puts "Scope: this check only evaluated the '#{report['surface']}' surface."
+        puts "       #{excluded.size} other required surface(s) were NOT checked: #{excluded.join(', ')}."
+        puts '       Run fp check per surface (or without --surface) to cover the whole project.'
+        puts
+      end
+
       # Requirements a proposed change has knocked back to draft. Informational, never a
       # violation — a human's review latency is not something to fail an agent's build
       # over. But they stay in the grid (proposing a change must not be a way out of the
@@ -302,9 +336,13 @@ module Fp
         puts
       end
 
-      def print_verdict(passed, violations, opts)
+      def print_verdict(passed, violations, opts, report = {})
+        # A scoped pass is not a project pass: say which surface it passed for, so nobody
+        # reads "Gate passed" as "the whole project is covered" (Fizzy #1490).
+        scope = report['scoped'] ? " for surface '#{report['surface']}' (other required surfaces not checked)" : ''
+
         if passed
-          puts 'Gate passed.'
+          puts "Gate passed#{scope}."
         elsif opts[:warn_only]
           puts "Gate FAILED with #{violations.size} violation(s) — exiting 0 because --warn-only was given."
         else

data/lib/fp/commands/ci_report.rb

@@ -50,6 +50,23 @@ module Fp
     # the default branch to record the real `passing`, superseding any pr_passing a prior
     # PR run left behind.
     class CiReport < Base
+      help_summary 'CI only: ingest real pass/fail results (writes passing/failing evidence)'
+      help_usage 'fp ci-report --junit <file>... --project <slug> --surface <surface> --ci-url URL [--pr URL]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Surface the suite covers', required: true
+      help_flag :test_type, 'Default test kind for markers that pin none'
+      help_flag :ci_url, 'CI run URL to record on the evidence'
+      help_flag :pr, "Mark this as a PR's CI: passing tests recorded as pr_passing, no merged evidence demoted"
+      help_flag :junit, 'JUnit XML report (repeatable to combine a surface split across shards)'
+      help_flag :base_dir, "Where the report's relative test-file paths resolve from (e.g. frontend)"
+      help_flag :repo, 'Repository the tests live in (org/repo)'
+      help_flag :sha, 'Checkout commit SHA'
+      help_flag :allow_empty, 'Do not error when a report resolves no fp:<slug> markers'
+      help_example 'fp ci-report --junit junit.xml --project stowzilla --surface api --ci-url "$CI_RUN_URL"'
+      help_example 'fp ci-report --junit web.xml --surface web --base-dir frontend --pr "$PR_URL"'
+      help_note "This is CI's command, not an agent's: only it writes passing/failing. Run it on both\n" \
+                'green and red builds (if: always()) so failures show on the matrix.'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,