featureparity 0.0.20 → 0.0.22

data/lib/fp/commands/propose_change.rb

@@ -10,11 +10,36 @@ module Fp
     # asked for, and what prompted the ask. The requirement drops back to draft until a
     # human reviews the diff — agents never approve their own changes.
     class ProposeChange < Base
+      help_summary 'Propose a change to an existing requirement (or --removal to retire it)'
+      help_usage 'fp propose-change <slug> --project <slug> [--name/--why/--acceptance ...] --reason "..."',
+                 'fp propose-change <slug> --removal --reason "..."'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :name, 'Proposed new title'
+      help_flag :why, 'Proposed new Why'
+      help_flag :acceptance, 'Proposed new acceptance criteria'
+      help_flag :required, 'Proposed new required surfaces (comma-separated; cannot remove a surface)'
+      help_flag :required_types, 'Proposed new required test types (comma-separated)'
+      help_flag :category, 'Proposed new category: functional, non-functional, ux, performance, security, compliance'
+      help_flag :parent, "Set the parent requirement's slug"
+      help_flag :no_parent, 'Propose un-nesting the requirement back to the top level (clears --parent)'
+      help_flag :slug, 'Proposed new slug (evidence follows; markers still need updating)'
+      help_flag :reason, 'What prompted this change (use this, not --source-*, to record the prompt)'
+      help_flag :removal, 'Propose deleting the requirement instead of changing it'
+      help_flag :withdraw, 'Take back the open proposal you authored, restoring the requirement as it was'
+      help_flag :source_type, "Correct the requirement's recorded origin type (not the change's prompt)"
+      help_flag :source_url, "Correct the requirement's recorded origin URL"
+      help_flag :source_context, "Correct the requirement's recorded origin context"
+      help_example 'fp propose-change print_qr --project stowzilla --acceptance "QR scans after 24h at -20C" --reason "Cold-chain rollout"'
+      help_example 'fp propose-change print_qr --removal --reason "Superseded by print_container_label"'
+      help_note "Applies the change and drops the requirement to draft for a human to review. Use --reason\n" \
+                "to say what prompted it; --source-* overwrite the requirement's own origin fields."
+
       KNOWN_FLAGS = {
         project: :string, name: :string, why: :string, acceptance: :string,
         required: :string, required_types: :string, category: :string, parent: :string, slug: :string,
+        no_parent: :boolean,
         reason: :string, source_type: :string, source_url: :string, source_context: :string,
-        removal: :boolean
+        removal: :boolean, withdraw: :boolean
       }.freeze
 
       VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
@@ -39,17 +64,21 @@ module Fp
           exit 1
         end
 
+        validate_flag_combinations!(opts)
         validate_enums!(opts)
 
         project_id = resolve_project_id(opts[:project])
         requirement = find_requirement!(project_id, slug)
 
+        return withdraw!(requirement, slug) if opts[:withdraw]
+
         params = build_params(opts, project_id)
         removal = opts[:removal] ? true : false
 
         if !removal && params.keys.none? { |k| proposed_field?(k) }
           output.error('Nothing to propose. Pass at least one of --name/--slug/--why/--acceptance/' \
-                       '--required/--required-types/--category/--parent, or --removal to propose deletion.')
+                       '--required/--required-types/--category/--parent/--no-parent, or --removal to ' \
+                       'propose deletion.')
           exit 1
         end
 
@@ -68,6 +97,31 @@ module Fp
 
       private
 
+      # Withdraw the requirement's own open proposal (Fizzy #1492). The single-open-
+      # proposal rule means an agent that wants to *amend* what it proposed can't just
+      # open a second one — it withdraws the first (restoring the requirement to what it
+      # was) and proposes again. The server only lets the proposal's author withdraw it.
+      def withdraw!(requirement, slug)
+        change_id = requirement['pending_change_id']
+        if change_id.nil? || change_id.to_s.empty?
+          output.error("Requirement '#{slug}' has no open proposal to withdraw.")
+          exit 1
+        end
+
+        result = client.withdraw_requirement_change(requirement['id'], change_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        output.success(result[:data]) do
+          puts "Withdrew the open proposal for '#{slug}'."
+          puts
+          puts 'The requirement is restored to what it was before the proposal.'
+          puts 'To amend it, propose the change again with the corrected values.'
+        end
+      end
+
       # A 409 means the requirement already has an open proposal — the one-at-a-time rule
       # (two "what it was" snapshots would make a rollback ambiguous). Rather than a dead
       # end, show what the open proposal is and point at `fp comment` so the agent can
@@ -109,6 +163,20 @@ module Fp
         warn '  Fields:   ' + changes.keys.join(', ')
       end
 
+      # --parent and --no-parent contradict each other, and --withdraw is a standalone
+      # verb that ignores proposed values (Fizzy #1492).
+      def validate_flag_combinations!(opts)
+        if opts[:parent] && opts[:no_parent]
+          output.error('Pass either --parent <slug> or --no-parent, not both.')
+          exit 1
+        end
+
+        return unless opts[:withdraw] && opts[:removal]
+
+        output.error('--withdraw cancels an open proposal; it cannot be combined with --removal.')
+        exit 1
+      end
+
       def validate_enums!(opts)
         if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
           output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")
@@ -143,6 +211,9 @@ module Fp
           params[:required_test_types] = opts[:required_types].split(',').map { |t| t.strip.downcase }.reject(&:empty?)
         end
         params[:parent_id] = resolve_parent_id(project_id, opts[:parent]) if opts[:parent]
+        # --no-parent un-nests a child back to top level: an empty parent_id. The server
+        # treats "" as "no parent" and diffs it against the current parent (Fizzy #1492).
+        params[:parent_id] = '' if opts[:no_parent]
 
         params[:removal] = true if opts[:removal]
         params[:reason] = opts[:reason] if opts[:reason]

data/lib/fp/commands/report.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'attach'
+
 module Fp
   module Commands
     # Single requirement:
@@ -8,13 +10,39 @@ module Fp
     #
     # Batch from a JUnit XML report (upload evidence without CI):
     #   fp report --junit <path> --project <slug> --surface X --repo org/repo
-    #     [--base-dir DIR] [--pr URL] [--sha X] [--work-item URL] [--ci-url URL] [--state present|stub]
+    #     [--base-dir DIR] [--attach-media] [--pr URL] [--sha X] [--work-item URL] [--ci-url URL] [--state present|stub]
     #
     # In --junit mode the CLI parses the report, discovers the fp:<slug> markers
     # in the referenced test files, and uploads evidence for every requirement
     # the suite covered. This lets an agent run the suite locally and report
-    # evidence without waiting on CI.
+    # evidence without waiting on CI. Playwright's reporter is handled natively:
+    # the › / :: title separators, a classname relative to the runner's testDir,
+    # and (with --attach-media) the [[ATTACHMENT|…]] videos it records.
     class Report < Base
+      help_summary 'Report test evidence for a requirement (agents report present/stub only)'
+      help_usage 'fp report <slug> --project <slug> --surface <surface> --file <path> --repo <org/repo>',
+                 'fp report --junit <file> --project <slug> --surface <surface> --repo <org/repo>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Surface this evidence is for', required: true
+      help_flag :test_type, "Kind of test (project's vocabulary, e.g. unit, integration, e2e)"
+      help_flag :file, 'Path to the test file (single-requirement mode)', required: true
+      help_flag :line, 'Line number of the test within the file'
+      help_flag :repo, 'Repository the test lives in (org/repo)', required: true
+      help_flag :pr, 'Pull request URL'
+      help_flag :sha, 'Commit SHA the evidence was observed at'
+      help_flag :work_item, 'Work-item URL (card/issue) that prompted the work'
+      help_flag :ci_url, 'CI run URL'
+      help_flag :title, 'Human-readable example/test name to display'
+      help_flag :state, 'Evidence state: present or stub (default present)'
+      help_flag :junit, 'JUnit XML report to batch-upload evidence from'
+      help_flag :base_dir, 'Where relative test-file paths in the report resolve from'
+      help_flag :attach_media, 'With --junit: upload the videos/screenshots the run recorded ([[ATTACHMENT|…]]) as visual evidence'
+      help_example 'fp report print_container_qr --project stowzilla --surface api --file spec/qr_spec.rb --repo stowzilla/app'
+      help_example 'fp report --junit junit.xml --project stowzilla --surface api --repo stowzilla/app',
+                   'Batch-upload from a JUnit report (slugs come from fp:<slug> markers)'
+      help_note "Agents report 'present' or 'stub' only. CI writes 'passing'/'failing' via fp ci-report.\n" \
+                'Always pass --test-type when a surface has more than one suite, or they overwrite each other.'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
@@ -29,7 +57,8 @@ module Fp
         title: :string,
         state: :string,
         junit: :string,
-        base_dir: :string
+        base_dir: :string,
+        attach_media: :boolean
       }.freeze
 
       VALID_STATES = %w[present stub].freeze
@@ -212,6 +241,9 @@ module Fp
         bindings = result[:bindings]
         unmatched = result[:unmatched]
         missing_surface = result[:missing_surface] || []
+        media = result[:media] || []
+        empty_name = result[:empty_name] || []
+        collisions = result[:collisions] || []
 
         # Markers that pinned no surface AND no --surface default was given.
         unless missing_surface.empty?
@@ -232,13 +264,16 @@ module Fp
         reported = []
         skipped_unknown = []
         api_unavailable = false
+        # slug -> requirement record (or nil when the slug names no requirement), so a
+        # slug looked up for evidence isn't fetched again to upload its media.
+        requirement_cache = {}
 
         bindings.each do |binding|
           state = state_override || binding.state
 
           # Verify the requirement exists before reporting (skip unknown slugs
           # with a warning rather than aborting the whole batch).
-          req_result = client.find_requirement_by_slug(project_id, binding.slug)
+          req_result = requirement_cache[binding.slug] ||= client.find_requirement_by_slug(project_id, binding.slug)
           unless req_result[:ok]
             skipped_unknown << binding
             next
@@ -280,7 +315,69 @@ module Fp
                         stored_source: stored_source_from(report_result) }
         end
 
-        emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
+        uploaded_media = []
+        if opts[:attach_media]
+          uploaded_media = upload_media(opts, media, base_dir, project_id, requirement_cache)
+        end
+
+        emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable, collisions,
+                           empty_name: empty_name, media: media, uploaded_media: uploaded_media)
+      end
+
+      # Upload the media (videos/screenshots) a run recorded for its bound testcases as
+      # visual evidence, one per MediaBinding, nesting each under the test it proves via
+      # example_title. Unknown slugs and unsupported/oversized files are skipped with a
+      # note rather than aborting the batch. Reuses the slug->requirement cache the
+      # evidence loop already filled.
+      def upload_media(opts, media, base_dir, project_id, requirement_cache)
+        media.map do |m|
+          path = File.expand_path(m.path, base_dir)
+          req_result = requirement_cache[m.slug] ||= client.find_requirement_by_slug(project_id, m.slug)
+
+          outcome = { slug: m.slug, surface: m.surface, path: m.path, example_title: m.example_title }
+          if !req_result[:ok]
+            outcome.merge(uploaded: false, reason: 'unknown requirement')
+          else
+            requirement_id = req_result[:data].dig('requirement', 'id')
+            upload_one_media(requirement_id, path, m, opts).merge(
+              slug: m.slug, surface: m.surface, path: m.path, example_title: m.example_title
+            )
+          end
+        end
+      end
+
+      # Presign → PUT → create, mirroring `fp attach`, for a single media file.
+      def upload_one_media(requirement_id, path, media_binding, opts)
+        return { uploaded: false, reason: 'file not found' } unless File.file?(path)
+
+        filename = File.basename(path)
+        ext = File.extname(filename).delete('.').downcase
+        content_type = Fp::Commands::Attach::CONTENT_TYPES[ext]
+        return { uploaded: false, reason: "unsupported type .#{ext}" } unless content_type
+
+        size = File.size(path)
+        return { uploaded: false, reason: 'empty file' } if size.zero?
+        if size > Fp::Commands::Attach::MAX_FILE_SIZE
+          return { uploaded: false, reason: 'file too large' }
+        end
+
+        presign = client.presign_attachment(requirement_id, filename: filename,
+                                             content_type: content_type, size_bytes: size)
+        return { uploaded: false, reason: presign[:error] || 'presign failed' } unless presign[:ok]
+
+        p = presign[:data]['presign']
+        up = client.upload_to_presigned_url(p['upload_url'], path, content_type)
+        return { uploaded: false, reason: up[:error] || 'upload failed' } unless up[:ok]
+
+        created = client.create_attachment(requirement_id, attachment_id: p['attachment_id'],
+                                           s3_key: p['s3_key'], filename: filename,
+                                           content_type: content_type, size_bytes: size,
+                                           surface: media_binding.surface,
+                                           example_title: media_binding.example_title,
+                                           test_run_url: opts[:ci_url], sha: opts[:sha])
+        return { uploaded: false, reason: created[:error] || 'create failed' } unless created[:ok]
+
+        { uploaded: true }
       end
 
       # Pull the stored status/source out of the server's echoed evidence record so the
@@ -299,12 +396,17 @@ module Fp
         (data['evidence'] || {})['source']
       end
 
-      def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
+      def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable, collisions = [],
+                             empty_name: [], media: [], uploaded_media: [])
         data = {
           repo: opts[:repo],
           reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, test_type: r[:binding].test_type, file: r[:binding].file, line: r[:binding].line, state: r[:state], recorded: r[:recorded], stored_status: r[:stored_status], superseded_by_ci: ci_superseded?(r[:state], r[:stored_status], r[:stored_source]) } },
           skipped_unknown: skipped_unknown.map { |b| { slug: b.slug, surface: b.surface, file: b.file } },
-          unmatched_testcases: unmatched.map { |tc| { name: tc.name, file: tc.file } }
+          unmatched_testcases: unmatched.map { |tc| { name: tc.name, file: tc.file } },
+          empty_name: empty_name,
+          media: media.map { |m| { slug: m.slug, surface: m.surface, path: m.path, example_title: m.example_title } },
+          uploaded_media: uploaded_media,
+          collisions: collisions.map { |c| { slug: c[:slug], surface: c[:surface], test_type: c[:test_type], files: c[:files] } }
         }
 
         output.success(data) do
@@ -324,6 +426,8 @@ module Fp
             puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}#{type}  (#{shown_state})  #{loc}"
           end
 
+          emit_collision_warning(collisions)
+
           unless skipped_unknown.empty?
             puts
             puts "⚠️  Skipped #{skipped_unknown.length} marker(s) with no matching requirement in this project:"
@@ -335,12 +439,58 @@ module Fp
             puts "ℹ️  #{unmatched.length} testcase(s) had no fp:<slug> marker and were skipped."
           end
 
+          unless empty_name.empty?
+            puts
+            puts "⚠️  #{empty_name.length} bound testcase(s) have an empty name — the receipt will have no title."
+            puts '    This is almost always an upstream reporter problem; check the JUnit XML.'
+            empty_name.each { |e| puts "     - #{e[:slug]} → #{e[:surface]} (#{e[:file]})" }
+          end
+
+          unless media.empty?
+            puts
+            if opts[:attach_media]
+              ok = uploaded_media.count { |m| m[:uploaded] }
+              puts "📎 Uploaded #{ok}/#{media.length} media attachment(s):"
+              uploaded_media.each do |m|
+                mark = m[:uploaded] ? '✓' : '✗'
+                title = m[:example_title] ? " [#{m[:example_title]}]" : ''
+                suffix = m[:uploaded] ? '' : "  (skipped: #{m[:reason]})"
+                puts "  #{mark} #{m[:slug]} → #{m[:surface]}#{title}  #{m[:path]}#{suffix}"
+              end
+            else
+              puts "📎 #{media.length} media attachment(s) found in the report (e.g. Playwright videos)."
+              puts '    Pass --attach-media to upload them as visual evidence.'
+            end
+          end
+
           if api_unavailable
             puts
             puts '⚠️  Evidence API not available yet. These will be recorded when #1214 is complete.'
           end
         end
       end
+
+      # Warn when two or more distinct test files in this run resolved to the *same*
+      # evidence cell. Server-side identity is (project, slug, surface, repo, test_type) —
+      # the file isn't part of it — so those reports upsert the same row and the last one
+      # posted wins. The suites silently overwrite each other, and only one survives on the
+      # matrix. It's almost always the `unspecified` default: neither suite pinned a test
+      # type. Make it loud and point at the fix.
+      def emit_collision_warning(collisions)
+        return if collisions.nil? || collisions.empty?
+
+        puts
+        puts "⚠️  #{collisions.length} evidence cell(s) were fed by more than one test file in this run."
+        puts '    These share one evidence row server-side, so the last report wins and the'
+        puts '    others are silently overwritten. Give each kind of test its own test type'
+        puts '    (a `:type` marker suffix, e.g. fp:slug@surface:e2e, or --test-type) so they'
+        puts '    become distinct cells instead of colliding:'
+        collisions.each do |c|
+          type = c[:test_type] ? c[:test_type] : 'unspecified'
+          puts "     - #{c[:slug]} → #{c[:surface]} [#{type}] collided across:"
+          c[:files].each { |f| puts "         #{f}" }
+        end
+      end
     end
   end
 end

data/lib/fp/commands/repos.rb

@@ -16,6 +16,17 @@ module Fp
     #   fp repos list [--project <slug>]
     #   fp repos unset <surface> --project <slug>
     class Repos < Base
+      help_summary 'Map surfaces to local repo paths on this machine'
+      help_usage 'fp repos set <surface> <path> --project <slug> [--repo org/repo]',
+                 'fp repos get <surface> --project <slug>',
+                 'fp repos list [--project <slug>]',
+                 'fp repos unset <surface> --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :repo, 'Optional org/repo to record alongside the local path (set only)'
+      help_example 'fp repos set customer_android ~/code/customer-android --project stowzilla --repo stowzilla/customer-android'
+      help_example 'cd "$(fp repos get customer_android --project stowzilla)"'
+      help_note 'Stored per-installation in ~/.config/fp/config.yml, not in the web app.'
+
       KNOWN_FLAGS = {
         project: :string,
         repo: :string

data/lib/fp/commands/setup.rb

@@ -6,6 +6,17 @@ module Fp
     # Interactive guided setup for new users.
     # Validates the API key, checks connectivity, and saves a profile.
     class Setup < Base
+      help_summary 'Interactive first-time setup: validate a key and save a profile'
+      help_usage 'fp setup',
+                 'fp setup --api-key fp_... [--profile NAME] [--non-interactive]'
+      help_flag :api_key, 'API key to validate and save (starts with fp_)'
+      help_flag :profile, 'Profile name to write (defaults to default)'
+      help_flag :api_url, 'Override API URL'
+      help_flag :environment, 'Named environment for the profile'
+      help_flag :non_interactive, 'Do not prompt; require flags to be supplied'
+      help_example 'fp setup'
+      help_example 'fp setup --api-key fp_... --profile ci-agent --non-interactive'
+
       KNOWN_FLAGS = {
         api_key: :string,
         profile: :string,

data/lib/fp/commands/show.rb

@@ -5,6 +5,11 @@ module Fp
     # fp show <slug> --project <slug>
     # Show requirement details including evidence receipts
     class Show < Base
+      help_summary 'Show a requirement, its acceptance criteria, and evidence receipts'
+      help_usage 'fp show <slug> --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_example 'fp show print_container_qr --project stowzilla'
+
       def run(args)
         opts, positional = parse_flags(args)
         require_project!(opts)
@@ -31,14 +36,20 @@ module Fp
         # every requirement no matter how many receipts have been filed.
         evidence = fetch_evidence(project_id, slug)
 
+        # Attachments (screenshots, recordings, downloadable files) live on their own
+        # collection keyed by the requirement's id, so fetch them here to show an agent
+        # what visual evidence is already on the requirement without a second command.
+        attachments = fetch_attachments(requirement['id'])
+
         # Agents only ever speak slugs, so translate the parent's ID back into one.
         parent_slug = resolve_parent_slug(project_id, requirement['parent_id'])
 
-        payload = result[:data].merge('evidence' => evidence)
+        payload = result[:data].merge('evidence' => evidence, 'attachments' => attachments)
         payload['parent_slug'] = parent_slug if parent_slug
 
         output.success(payload) do
-          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug, source_history: source_history)
+          print_requirement(requirement, evidence: evidence, attachments: attachments,
+                                          parent_slug: parent_slug, source_history: source_history)
         end
       end
 
@@ -51,6 +62,15 @@ module Fp
         result[:data]['evidence'] || []
       end
 
+      def fetch_attachments(requirement_id)
+        return [] if requirement_id.to_s.empty?
+
+        result = client.list_attachments(requirement_id)
+        return [] unless result[:ok]
+
+        result[:data]['attachments'] || []
+      end
+
       def resolve_parent_slug(project_id, parent_id)
         return nil if parent_id.nil? || parent_id.to_s.empty?
 
@@ -61,7 +81,7 @@ module Fp
         parent && parent['slug']
       end
 
-      def print_requirement(req, evidence: [], parent_slug: nil, source_history: [])
+      def print_requirement(req, evidence: [], attachments: [], parent_slug: nil, source_history: [])
         puts "#{req['title']}"
         puts "=" * req['title'].length
         puts
@@ -156,10 +176,29 @@ module Fp
             end
         end
 
+        print_attachments(attachments)
+
         puts "Created:  #{req['created_at']}"
         puts "Updated:  #{req['updated_at']}"
         puts "By:       #{req['created_by']}" if req['created_by']
       end
+
+      # Attachments: visual evidence (screenshots, recordings) and downloadable files on
+      # the requirement, so an agent can see what's already captured without a separate
+      # command. Shown even when empty so the absence is explicit (Fizzy #1488).
+      def print_attachments(attachments)
+        puts 'Attachments:'
+        if attachments.empty?
+          puts '  (none)'
+        else
+          attachments.each do |att|
+            puts "  #{att['id']}  #{att['filename']}"
+            puts "    Surface: #{att['surface']}" if att['surface'] && !att['surface'].to_s.empty?
+            puts "    Test:    #{att['example_title']}" if att['example_title'] && !att['example_title'].to_s.empty?
+          end
+        end
+        puts
+      end
     end
   end
 end

data/lib/fp/commands/showroom.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp showroom --project <slug>   - the client showroom, as a client will see it
+    #
+    # The showroom (Fizzy #1479) is the one page a client gets: the welcome note, then
+    # a card per surface with a link, a button label, and instructions. Its content is
+    # written through `fp projects edit --showroom-welcome` and `fp surfaces edit
+    # --showroom-*`, and this command is how an agent checks the result without a
+    # browser: the same payload the client is served, plus the surfaces that are *not*
+    # on it and why, so a card that silently dropped out (both fields cleared) is
+    # noticed.
+    #
+    # Whether the share link is on is a human's business — the API refuses an agent's
+    # key — so it is reported as unknown rather than guessed at.
+    class Showroom < Base
+      help_summary 'Preview the client showroom exactly as a client will see it'
+      help_usage 'fp showroom --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_example 'fp showroom --project stowzilla'
+      help_note "Prints the welcome note and each surface's card, then the surfaces that are NOT shown and why.\n" \
+                "Write the content with `fp projects edit --showroom-welcome` and `fp surfaces edit --showroom-*`.\n" \
+                'The share link is reported as unknown: only a person can see or change it.'
+      def run(args)
+        opts, = parse_flags(args)
+        require_project!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+
+        result = client.get_showroom(project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        showroom = result[:data]['showroom'] || {}
+        shown_ids = (showroom['surfaces'] || []).map { |surface| surface['id'] }
+        hidden = hidden_surfaces(project_id, shown_ids)
+        share = share_link_status(project_id)
+
+        output.success({ showroom: showroom, hidden: hidden, share_link: share, project: opts[:project] }) do
+          print_showroom(showroom, hidden, share, project: opts[:project])
+        end
+      end
+
+      private
+
+      # Surfaces with neither a link nor instructions. The showroom payload leaves them
+      # out, so they are read from the surface list instead.
+      def hidden_surfaces(project_id, shown_ids)
+        result = client.list_surfaces(project_id)
+        return [] unless result[:ok]
+
+        (result[:data]['surfaces'] || []).reject { |surface| shown_ids.include?(surface['id']) }.map do |surface|
+          { 'key' => surface['key'], 'name' => surface['name'], 'kind' => surface['kind'],
+            'reason' => 'no showroom link or instructions' }
+        end
+      end
+
+      # { 'state' => 'on' | 'off' | 'unknown', 'token' => ..., 'reason' => ... }
+      def share_link_status(project_id)
+        result = client.get_showroom_share_link(project_id)
+        if result[:ok]
+          link = result[:data]['share_link']
+          link ? { 'state' => 'on', 'token' => link['token'], 'created_by' => link['created_by'] } : { 'state' => 'off' }
+        elsif result[:status] == 403
+          { 'state' => 'unknown', 'reason' => 'only a person can see or change the share link (Project Settings → Showroom)' }
+        else
+          { 'state' => 'unknown', 'reason' => result[:error] }
+        end
+      end
+
+      def print_showroom(showroom, hidden, share, project:)
+        info = showroom['project'] || {}
+        title = "Showroom: #{info['name'] || project}"
+        puts title
+        puts '=' * title.length
+        puts
+
+        welcome = text_or_nil(info['welcome'])
+        if welcome
+          puts 'Welcome:'
+          welcome.each_line { |line| puts "  #{line.rstrip}" }
+        else
+          puts 'Welcome: (none) — set one with: fp projects edit ' \
+               "#{info['slug'] || project} --showroom-welcome \"...\""
+        end
+        puts
+
+        surfaces = showroom['surfaces'] || []
+        if surfaces.empty?
+          puts 'Surfaces shown: none. The client sees only the welcome note.'
+        else
+          puts "Surfaces shown (#{surfaces.size}):"
+          surfaces.each { |surface| print_card(surface) }
+        end
+
+        unless hidden.empty?
+          puts
+          puts "Not shown (#{hidden.size}):"
+          hidden.each do |surface|
+            puts "  - #{surface['name'] || surface['key']} (#{surface['key']}): #{surface['reason']}"
+          end
+          puts "  Add one with: fp surfaces edit <key> --project #{project} --showroom-url ... " \
+               '--showroom-instructions-file ...'
+        end
+
+        puts
+        case share['state']
+        when 'on'
+          puts "Share link: on (created by #{share['created_by'] || 'unknown'}) — the content above is live."
+        when 'off'
+          puts 'Share link: off — only signed-in clients and the team can see this.'
+        else
+          puts "Share link: unknown — #{share['reason']}"
+        end
+      end
+
+      def print_card(surface)
+        puts
+        puts "  #{surface['name']} (#{surface['kind']})"
+        url = text_or_nil(surface['url'])
+        label = text_or_nil(surface['label'])
+        puts "    Link:         #{url ? "#{url}#{label ? " [#{label}]" : ''}" : '(none)'}"
+        instructions = text_or_nil(surface['instructions'])
+        if instructions
+          puts '    Instructions:'
+          instructions.each_line { |line| puts "      #{line.rstrip}" }
+        else
+          puts '    Instructions: (none)'
+        end
+      end
+
+      def text_or_nil(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+    end
+  end
+end