featureparity 0.0.21 → 0.0.22

data/lib/fp/commands/surfaces.rb

@@ -18,6 +18,13 @@ module Fp
     # surface with the same key, and there was no way to fix that short of a raw API call
     # (Fizzy #1480). The server now refuses a duplicate key with a 409; `add` turns that
     # into a pointer at `edit`. `delete` is guarded like `fp projects delete`.
+    #
+    # `edit` also keeps the surface's client-showroom card (Fizzy #1479): the link a
+    # client opens, the button text, and how to sign in and try it. The agent that
+    # deployed the surface and made the demo accounts is the one that knows these, so
+    # it fills them in rather than leaving a human to retype them. Pass an empty value
+    # to clear a field; a surface with neither a link nor instructions leaves the
+    # showroom. Feedback and the share link stay with humans (`fp showroom` explains).
     class Surfaces < Base
       ADD_FLAGS = {
         project: :string,
@@ -28,7 +35,14 @@ module Fp
         default_branch: :string
       }.freeze
 
-      EDIT_FLAGS = ADD_FLAGS.merge(key: :string).freeze
+      SHOWROOM_FLAGS = {
+        showroom_url: :string,
+        showroom_label: :string,
+        showroom_instructions: :string,
+        showroom_instructions_file: :string
+      }.freeze
+
+      EDIT_FLAGS = ADD_FLAGS.merge(key: :string).merge(SHOWROOM_FLAGS).freeze
 
       DELETE_FLAGS = {
         project: :string,
@@ -38,6 +52,28 @@ module Fp
       VALID_KINDS = %w[api web android ios other].freeze
       VALID_AUDIENCES = %w[customer ops both internal].freeze
 
+      help_summary 'List, view, create, edit, and delete a project\'s surfaces'
+      help_usage 'fp surfaces --project <slug>',
+                 'fp surfaces show <key> --project <slug>',
+                 'fp surfaces add <key> --project <slug> [--name ...] [--kind K] [--repo org/repo]',
+                 'fp surfaces edit <key> --project <slug> [flags]',
+                 'fp surfaces delete <key> --project <slug> [--yes]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :name, 'Human-readable surface name'
+      help_flag :kind, "Surface kind: #{VALID_KINDS.join(', ')}"
+      help_flag :audience, "Audience: #{VALID_AUDIENCES.join(', ')}"
+      help_flag :repo, 'Repository the surface maps to (org/repo)'
+      help_flag :default_branch, 'Default branch for the repo'
+      help_flag :showroom_url, 'Client showroom card: the http(s) link a client opens (edit; empty clears)'
+      help_flag :showroom_label, 'Client showroom card: the button text for that link (edit)'
+      help_flag :showroom_instructions, 'Client showroom card: how to sign in and try the surface (edit)'
+      help_flag :showroom_instructions_file, 'Read --showroom-instructions from a file (multi-line)'
+      help_flag :yes, 'Skip the typed-key confirmation on delete'
+      help_example 'fp surfaces --project stowzilla'
+      help_example 'fp surfaces add customer_android --project stowzilla --kind android --repo stowzilla/customer-android'
+      help_example 'fp surfaces delete web --project stowzilla --yes'
+      help_example 'fp surfaces edit web --project stowzilla --showroom-url https://dev.example.com --showroom-instructions-file docs/showroom/web.txt'
+
       def run(args)
         # Subcommand dispatch. Bare `fp surfaces --project X` stays a list, so existing
         # callers (and the docs) keep working.
@@ -167,7 +203,9 @@ module Fp
         key = positional.first
         if key.nil? || key.strip.empty?
           output.error('Usage: fp surfaces edit <key> --project <slug> [--name "Name"] [--kind ...] ' \
-                       '[--audience ...] [--repo org/repo] [--default-branch main] [--key new_key]')
+                       '[--audience ...] [--repo org/repo] [--default-branch main] [--key new_key] ' \
+                       '[--showroom-url URL] [--showroom-label "..."] ' \
+                       '[--showroom-instructions "..." | --showroom-instructions-file PATH]')
           exit 1
         end
 
@@ -179,9 +217,11 @@ module Fp
         %i[key name kind audience repo default_branch].each do |field|
           params[field] = opts[field] if opts.key?(field)
         end
+        params.merge!(showroom_params(opts))
 
         if params.empty?
-          output.error('Nothing to change. Pass --name, --kind, --audience, --repo, --default-branch, or --key.')
+          output.error('Nothing to change. Pass --name, --kind, --audience, --repo, --default-branch, --key, ' \
+                       'or a --showroom-* flag.')
           exit 1
         end
 
@@ -208,9 +248,57 @@ module Fp
           puts "  Audience: #{record['audience']}"
           puts "  Repo:     #{record['repo'] || '(none)'}"
           puts "  Branch:   #{record['default_branch'] || '(none)'}"
+          print_showroom(record, indent: '  ') if params.keys.any? { |field| field.to_s.start_with?('showroom_') }
         end
       end
 
+      # The showroom fields from --showroom-* flags, as the API expects them. A string
+      # flag given as empty clears the field. The URL is checked here with the same rule
+      # the server applies (http/https only) so a typo fails before anything is sent.
+      def showroom_params(opts)
+        if opts.key?(:showroom_instructions) && opts.key?(:showroom_instructions_file)
+          output.error('Pass --showroom-instructions or --showroom-instructions-file, not both.')
+          exit 1
+        end
+
+        params = {}
+        %i[showroom_url showroom_label showroom_instructions].each do |field|
+          params[field] = flag_text(opts[field]) if opts.key?(field)
+        end
+
+        if opts.key?(:showroom_instructions_file)
+          params[:showroom_instructions] = read_text_file!(opts[:showroom_instructions_file],
+                                                           '--showroom-instructions-file')
+        end
+
+        url = params[:showroom_url]
+        if url && !url.empty? && url !~ %r{\Ahttps?://\S+\z}i
+          output.error("Invalid --showroom-url '#{url}'. Must be an http:// or https:// link; " \
+                       'pass an empty value to clear it.')
+          exit 1
+        end
+
+        params
+      end
+
+      # A string flag given with no value parses as `true`; treat that as "clear it",
+      # the same as an explicit empty string.
+      def flag_text(value)
+        value == true ? '' : value.to_s
+      end
+
+      def read_text_file!(path, flag)
+        if path.nil? || path == true || path.to_s.strip.empty?
+          output.error("#{flag} needs a path")
+          exit 1
+        end
+        unless File.file?(path)
+          output.error("#{flag}: no such file '#{path}'")
+          exit 1
+        end
+        File.read(path).strip
+      end
+
       def delete(args)
         opts, positional = parse_flags(args, DELETE_FLAGS)
         require_project!(opts)
@@ -311,12 +399,37 @@ module Fp
           globs.each { |g| puts "  - #{g}" }
         end
 
+        puts
+        print_showroom(surface, indent: '')
+
         puts
         puts "ID:       #{surface['id']}" if surface['id']
         puts "Created:  #{surface['created_at']}" if surface['created_at']
         puts "Updated:  #{surface['updated_at']}" if surface['updated_at']
       end
 
+      # The surface's client-showroom card. Says plainly whether a client can see the
+      # surface, since that is decided by the content (a link or instructions), not a
+      # switch, and an agent that just wrote instructions should know they went live.
+      def print_showroom(surface, indent:)
+        url = text_or_nil(surface['showroom_url'])
+        label = text_or_nil(surface['showroom_label'])
+        instructions = text_or_nil(surface['showroom_instructions'])
+        shown = !(url.nil? && instructions.nil?)
+
+        puts "#{indent}Showroom: #{shown ? 'shown to clients' : 'hidden (no link or instructions)'}"
+        return unless shown
+
+        puts "#{indent}  Link:         #{url || '(none)'}#{label ? " [#{label}]" : ''}"
+        puts "#{indent}  Instructions: #{instructions ? '' : '(none)'}"
+        instructions&.each_line { |line| puts "#{indent}    #{line.rstrip}" }
+      end
+
+      def text_or_nil(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+
       # test_globs may arrive as a JSON string or an array; normalize to an array for
       # display. Blank/unparseable → empty (the server falls back to kind defaults).
       def normalize_test_globs(value)

data/lib/fp/commands/version.rb

@@ -4,6 +4,9 @@ module Fp
   module Commands
     # fp version
     class Version < Base
+      help_summary 'Show the installed fp version'
+      help_usage 'fp version'
+
       def run(_args)
         output.success({ version: Fp::VERSION }) do
           puts "fp #{Fp::VERSION}"

data/lib/fp/commands/whoami.rb

@@ -10,6 +10,12 @@ module Fp
     # (masked — never the full token). Purely local; makes no API calls, so it
     # works even without a valid key. Honors --profile / --api-url / --json.
     class Whoami < Base
+      help_summary 'Show the resolved config (profile, API URL, environment, masked key)'
+      help_usage 'fp whoami [--json]'
+      help_example 'fp whoami'
+      help_example 'fp --profile staging whoami'
+      help_note 'Purely local; makes no API calls, so it works even without a valid key.'
+
       def run(_args)
         r = config.resolved
 

data/lib/fp/commands.rb

@@ -3,6 +3,7 @@
 require_relative 'commands/base'
 require_relative 'commands/projects'
 require_relative 'commands/surfaces'
+require_relative 'commands/showroom'
 require_relative 'commands/list'
 require_relative 'commands/show'
 require_relative 'commands/propose'

data/lib/fp/junit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rexml/document'
+require 'pathname'
 require_relative 'source_fingerprint'
 
 module Fp
@@ -18,7 +19,8 @@ module Fp
     # is the runner's own verdict, which only CI is allowed to act on (`fp ci-report`).
     # Both are kept because they answer different questions: a red test still proves the
     # test exists (present), it just doesn't prove the requirement is met.
-    TestCase = Struct.new(:name, :classname, :file, :line, :status, :failed, keyword_init: true) do
+    TestCase = Struct.new(:name, :classname, :file, :line, :status, :failed, :attachments,
+                          keyword_init: true) do
       # Agents only ever report present/stub — never passing/failing (that's CI).
       # A skipped test is treated as a stub; anything else counts as present.
       def stub?
@@ -28,6 +30,12 @@ module Fp
       def failed?
         !!failed
       end
+
+      # Media (videos, screenshots, traces) the runner recorded for this test — e.g.
+      # Playwright's `[[ATTACHMENT|path]]` lines. Always an array.
+      def attachments
+        self[:attachments] || []
+      end
     end
 
     # One requirement's aggregated CI outcome for one surface, ready to hand to the
@@ -77,6 +85,12 @@ module Fp
     # test, so the marker line is a close stand-in when the runner omits lines).
     Binding = Struct.new(:slug, :surface, :test_type, :file, :line, :title, :state, keyword_init: true)
 
+    # A media file (video/screenshot) a run recorded for one bound testcase, ready for
+    # `fp report --junit --attach-media` to upload as visual evidence. Unlike Binding,
+    # these are per-testcase, not aggregated: a run can record a distinct video for every
+    # test, and `example_title` is what nests each capture under the receipt it proves.
+    MediaBinding = Struct.new(:slug, :surface, :path, :example_title, keyword_init: true)
+
     # Matches `fp:<slug>` inside a comment, with an optional `@surface` (or
     # `@surface1,surface2`) suffix to target one or more specific surfaces, and an
     # optional `:<type>` suffix to pin the kind of test:
@@ -132,13 +146,30 @@ module Fp
           file: resolve_file(el.attributes['file'], classname, suite_name),
           line: (el.attributes['line'] && el.attributes['line'].to_i),
           status: testcase_status(el),
-          failed: testcase_failed?(el)
+          failed: testcase_failed?(el),
+          attachments: extract_attachments(el)
         )
       end
 
       cases
     end
 
+    # Playwright's JUnit reporter records media (video, screenshots, trace) by writing
+    # `[[ATTACHMENT|<path>]]` lines into the testcase's `<system-out>`. Pull those paths
+    # out so `fp report --junit --attach-media` can upload them as visual evidence for the
+    # bound requirement, instead of a hand-matched `fp attach` per file.
+    #
+    # The path is relative to wherever Playwright ran; it's resolved against --base-dir at
+    # upload time, the same way test-file paths are.
+    ATTACHMENT_RE = /\[\[ATTACHMENT\|([^\]]+)\]\]/.freeze
+
+    def extract_attachments(el)
+      text = el.get_elements('system-out').map(&:text).compact.join("\n")
+      return [] if text.empty?
+
+      text.scan(ATTACHMENT_RE).map { |(path)| path.strip }.reject(&:empty?).uniq
+    end
+
     # Runners disagree about where the source file goes. Minitest- and RSpec-style reports
     # put it on the testcase's `file` attribute; vitest and jest omit `file` entirely and
     # carry the path in `classname` and the enclosing `<testsuite name>`. Markers live in
@@ -200,11 +231,20 @@ module Fp
     #     bindings: [Binding, ...],       # unique (slug, surface, file) evidence
     #     unmatched: [TestCase, ...],     # testcases with no discoverable marker
     #     missing_surface: [Binding-ish], # markers with no surface and no default
+    #     media: [MediaBinding, ...],     # attachments on bound testcases, per surface
+    #     empty_name: [{slug:, surface:, file:}], # bound testcases with a blank name
+    #     collisions: [{slug:,surface:,   # cells >1 distinct file fed — they overwrite
+    #       test_type:,files:}],          #   each other server-side (see detect_collisions)
     #   }
     def bind_markers(testcases, base_dir: Dir.pwd, default_surface: nil, default_test_type: nil)
       bindings = {}
       matched = {}
       missing_surface = []
+      media = []
+      empty_name = []
+      # Track which source files feed each evidence cell so we can spot the silent
+      # overwrite below (see detect_collisions).
+      cell_files = Hash.new { |h, k| h[k] = [] }
 
       walk_matches(testcases, base_dir) do |match|
         tc = match.testcase
@@ -222,15 +262,52 @@ module Fp
           if surface.nil? || surface.empty?
             missing_surface << { slug: marker[:slug], file: tc.file }
           else
+            cell_files[[marker[:slug], surface, test_type]] << match.repo_file
             record_binding(bindings, marker[:slug], surface, tc, marker,
                            titles_reliable: match.precise, file: match.repo_file,
                            test_type: test_type)
+
+            # A bound testcase with no name produces a receipt with no title, which is
+            # almost always an upstream reporter problem — flag it rather than filing a
+            # nameless receipt silently.
+            empty_name << { slug: marker[:slug], surface: surface, file: match.repo_file } if presence(tc.name).nil?
+
+            # Media the run recorded for this exact test, tied to its example title so
+            # each capture nests under the receipt it proves.
+            tc.attachments.each do |path|
+              media << MediaBinding.new(slug: marker[:slug], surface: surface, path: path,
+                                        example_title: (presence(tc.name) if match.precise))
+            end
           end
         end
       end
 
       unmatched = testcases.reject { |tc| matched[tc.object_id] }
-      { bindings: bindings.values, unmatched: unmatched, missing_surface: missing_surface.uniq }
+      { bindings: bindings.values, unmatched: unmatched, missing_surface: missing_surface.uniq,
+        media: media, empty_name: empty_name.uniq,
+        collisions: detect_collisions(cell_files) }
+    end
+
+    # Find evidence cells that more than one *distinct source file* resolved to in a
+    # single run. Server-side, evidence identity is (project, slug, surface, repo,
+    # test_type) — the file is deliberately not part of it, so one requirement cell is
+    # one row. That means two different test files (an RSpec unit suite and a Playwright
+    # e2e suite, say) that bind to the same slug+surface and share a test_type both upsert
+    # the *same* row: the second POST silently overwrites the first, and only one suite's
+    # evidence survives. This is almost always the `unspecified` default colliding —
+    # neither suite pinned a `:type` marker nor passed `--test-type`.
+    #
+    # Returns [{ slug:, surface:, test_type:, files: [sorted unique repo paths] }, ...]
+    # for every cell fed by two or more distinct files, so the caller can warn instead of
+    # overwriting in silence. A single file feeding a cell is the normal case and is not
+    # reported.
+    def detect_collisions(cell_files)
+      cell_files.filter_map do |(slug, surface, test_type), files|
+        distinct = files.compact.uniq
+        next if distinct.length < 2
+
+        { slug: slug, surface: surface, test_type: test_type, files: distinct.sort }
+      end
     end
 
     # Aggregate a run's results per (slug, surface) into the pass/fail verdict CI files.
@@ -346,14 +423,29 @@ module Fp
     # can never disagree about which test a marker annotates.
     def walk_matches(testcases, base_dir)
       marker_cache = {}
+      resolve_cache = {}
       root = repo_root_for(base_dir)
 
       # Group testcases by their source file so we can reason about ordering.
       testcases.group_by(&:file).each do |file, cases|
-        markers = markers_for(cases.first, base_dir, marker_cache)
+        # The report's path may not exist under base_dir (Playwright's classname is
+        # relative to its testDir, not the repo or cwd). Find the real file first; its
+        # resolved location is what we read markers from and what we report.
+        source_path = resolve_source_path(file, base_dir, resolve_cache)
+        markers = markers_for(source_path, marker_cache)
         next if markers.empty?
 
-        repo_file = repo_relative_path(file, base_dir, root)
+        # Report the file relative to the repo root. When the file was found exactly where
+        # the report said (the common case), keep the reported path verbatim — outside a
+        # git checkout that's all we have, and expanding it would change long-standing
+        # output. Only when the search *relocated* the file (Playwright's testDir case) do
+        # we report from its real location instead of the path that didn't exist.
+        repo_file =
+          if source_path && source_path != File.expand_path(file.to_s, base_dir)
+            repo_relative_path(source_path, base_dir, root)
+          else
+            repo_relative_path(file, base_dir, root)
+          end
 
         cases.each do |tc|
           marker, precise = marker_for(tc, cases, markers)
@@ -361,7 +453,7 @@ module Fp
 
           yield Match.new(
             testcase: tc, marker: marker, precise: precise, repo_file: repo_file,
-            source_path: File.expand_path(file, base_dir)
+            source_path: source_path || File.expand_path(file.to_s, base_dir)
           )
         end
       end
@@ -466,8 +558,11 @@ module Fp
       markers.max_by { |m| [m[:title].length, m[:line]] }
     end
 
-    # vitest/jest join describe names and the test name with " > ".
-    NAME_SEPARATOR = / > /.freeze
+    # How runners join an enclosing group's name to the test's. vitest/jest use " > ",
+    # Playwright uses " › " (U+203A), and pytest-style ids use "::"
+    # (file.py::TestClass::test_name, no surrounding spaces). Matching all three lets a
+    # marker bind by title regardless of which runner produced the report.
+    NAME_SEPARATOR = /\s+>\s+|\s+›\s+|::/.freeze
 
     def title_matches_test?(title, name, segments)
       return false if title.nil? || title.empty?
@@ -513,23 +608,123 @@ module Fp
                                   line: line, title: (testcase.name if titles_reliable), state: state)
     end
 
-    # Load and cache the fp:<slug> markers (with line numbers) for a testcase's
-    # source file. Returns [] when the file is unknown or unreadable.
-    def markers_for(testcase, base_dir, cache)
-      file = testcase.file
-      return [] if file.nil? || file.empty?
+    # Load and cache the fp:<slug> markers (with line numbers) for an already-resolved
+    # absolute source path. Returns [] when the path is nil or unreadable.
+    def markers_for(source_path, cache)
+      return [] if source_path.nil? || source_path.empty?
 
-      return cache[file] if cache.key?(file)
+      return cache[source_path] if cache.key?(source_path)
 
-      resolved = File.expand_path(file, base_dir)
       markers =
-        if File.file?(resolved)
-          scan_markers(File.read(resolved))
+        if File.file?(source_path)
+          scan_markers(File.read(source_path))
         else
           []
         end
 
-      cache[file] = markers
+      cache[source_path] = markers
+    end
+
+    # Common directories a test file lives under when the reported path is relative to a
+    # runner's testDir rather than the repo/cwd. Tried in order after base_dir itself.
+    COMMON_TEST_DIRS = %w[e2e tests test spec specs integration].freeze
+
+    # How many directory levels deep the last-resort **/<name> glob will search, so an
+    # unresolved path doesn't walk a whole monorepo.
+    GLOB_SEARCH_DEPTH = 6
+
+    # Resolve a report's test-file path to an absolute path that actually exists, so
+    # markers can be read from it. Returns nil when nothing matches.
+    #
+    # Playwright's JUnit reporter writes `classname="loyalty.spec.js"` — relative to its
+    # `testDir` (e.g. `frontend/e2e/`), not the repo root or the directory the runner was
+    # invoked from. So `<base-dir>/loyalty.spec.js` doesn't exist and every testcase ends
+    # up "had no fp: marker". Rather than make the user hand-annotate the XML, search:
+    #
+    #   1. base_dir itself (the path as reported) — the common, unambiguous case;
+    #   2. Playwright's testDir, read from a playwright.config.* under base_dir;
+    #   3. the usual test directories (e2e/, tests/, test/, spec/, ...);
+    #   4. a bounded **/<basename> glob, accepted only when it matches exactly one file.
+    #
+    # Prints which strategy found the file (unless silent) so a surprising resolution is
+    # visible rather than magic. Results are cached per reported path.
+    def resolve_source_path(file, base_dir, cache = {}, silent: false)
+      return nil if file.nil? || file.empty?
+      return cache[file] if cache.key?(file)
+
+      cache[file] = compute_source_path(file, base_dir, silent: silent)
+    end
+
+    def compute_source_path(file, base_dir, silent: false)
+      direct = File.expand_path(file, base_dir)
+      return direct if File.file?(direct)
+
+      candidates = source_path_candidates(file, base_dir)
+      found = candidates.find { |path| File.file?(path) }
+      if found
+        report_resolution(file, found, base_dir) unless silent
+        return found
+      end
+
+      globbed = glob_for_source(file, base_dir)
+      if globbed
+        report_resolution(file, globbed, base_dir) unless silent
+        return globbed
+      end
+
+      nil
+    end
+
+    # Ordered, non-glob candidate locations for a reported path: Playwright's testDir
+    # first (the authoritative answer when a config declares one), then the common test
+    # directories. Each is tried both with the full reported path and with just its
+    # basename, since Playwright reports a bare filename.
+    def source_path_candidates(file, base_dir)
+      basename = File.basename(file)
+      dirs = [playwright_test_dir(base_dir), *COMMON_TEST_DIRS].compact.uniq
+
+      dirs.flat_map do |dir|
+        base = File.expand_path(dir, base_dir)
+        [File.expand_path(file, base), File.join(base, basename)]
+      end.uniq
+    end
+
+    # The last resort: a bounded glob for the basename anywhere under base_dir. Only
+    # accepted when it resolves to exactly one file — an ambiguous match is no better
+    # than no match, and silently picking one would bind a marker from the wrong file.
+    def glob_for_source(file, base_dir)
+      basename = File.basename(file)
+      return nil if basename.empty?
+
+      pattern_dirs = (1..GLOB_SEARCH_DEPTH).map { |d| File.join(base_dir, *Array.new(d, '*')) }
+      matches = Dir.glob([File.join(base_dir, basename), *pattern_dirs.map { |p| "#{p}/#{basename}" }])
+                   .select { |p| File.file?(p) }.uniq
+      matches.length == 1 ? File.expand_path(matches.first) : nil
+    end
+
+    # Read Playwright's `testDir` from a playwright.config.{js,ts,mjs,cjs} under base_dir.
+    # The config is JS/TS, not something we can evaluate, so pull the string literal with
+    # a conservative regex. Returns nil when there's no config or no testDir in it.
+    def playwright_test_dir(base_dir)
+      config = Dir.glob(File.join(base_dir, 'playwright.config.{js,ts,mjs,cjs}')).first
+      return nil unless config && File.file?(config)
+
+      contents = File.read(config)
+      match = contents.match(/testDir\s*:\s*(['"`])(.+?)\1/)
+      match && match[2]
+    rescue StandardError
+      nil
+    end
+
+    # Tell the user which strategy resolved a path that wasn't where the report said,
+    # so a surprising resolution is visible. Printed to stderr to stay out of --json.
+    def report_resolution(reported, found, base_dir)
+      rel = begin
+        Pathname.new(found).relative_path_from(Pathname.new(File.expand_path(base_dir))).to_s
+      rescue StandardError
+        found
+      end
+      warn "fp: resolved test file '#{reported}' to '#{rel}' (not found at the reported path)"
     end
 
     # Scan file contents for fp:<slug>[@surface[,surface...]][:type] markers, returning

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.21'
+  VERSION = '0.0.22'
 end

data/skills/fp/SKILL.md

@@ -336,6 +336,30 @@ This also catches the one regression a green test suite can't: a test that was d
 renamed, or had its `fp:` marker stripped. Every remaining test passes, so CI is happy,
 while the requirement quietly lost its only proof.
 
+### 9. Fill in the client showroom when a surface is deployed
+
+The project's client (the person the software is being built for) sees one page: the
+showroom. It is a welcome note plus a card per surface — a link, a button label, and
+instructions for signing in and trying it. You deployed the surface, created the demo
+accounts, and know the URLs, so you fill the card in; a human retyping it into project
+settings is the step that goes stale.
+
+```bash
+fp showroom --project X                          # current state; hidden surfaces listed
+fp projects edit X --showroom-welcome-file docs/showroom/welcome.txt
+fp surfaces edit web --project X \
+  --showroom-url https://dev.example.com \
+  --showroom-label "Open the web app" \
+  --showroom-instructions-file docs/showroom/web.txt
+```
+
+Write instructions a non-technical reader can follow: where to click, which account to
+sign in as (a dedicated demo account, not the one your e2e suite mutates), what data is
+already there to look at, and one or two things worth trying. Keep the file in the repo
+(`docs/showroom/<surface>.txt`) so the next deploy can re-send it. A surface with neither
+a link nor instructions is not shown; clear both to take a card down. Feedback and the
+share link are human-only, so after writing the content tell a person it's ready.
+
 ### Repo-local config (`.featureparity.yml`)
 
 If a repo has a `.featureparity.yml`, `--project` is optional — `fp` reads the slug from
@@ -419,6 +443,9 @@ not as the fix — you still write the proposal.
 | List projects | `fp projects` |
 | Create a project | `fp projects create <slug> --name "..." --surfaces api,web` |
 | View / edit a project | `fp projects show <slug>`, `fp projects edit <slug> --name "..."` |
+| Preview the client showroom | `fp showroom --project X` |
+| Write a surface's showroom card | `fp surfaces edit <key> --project X --showroom-url ... --showroom-instructions-file ...` |
+| Write the showroom welcome | `fp projects edit <slug> --showroom-welcome-file ...` |
 
 All commands support `--json` for machine-readable output.
 

data/skills/fp/references/cli.md

@@ -36,7 +36,7 @@ fp projects                       # list
 fp projects --json
 fp projects show <slug>           # details + surfaces
 fp projects create <slug> --name "Name" [--description "..."] [--surfaces api,web]
-fp projects edit <slug> [--name "..."] [--description "..."]
+fp projects edit <slug> [--name "..."] [--description "..."] [--showroom-welcome "..." | --showroom-welcome-file PATH]
 fp projects delete <slug> [--yes]
 ```
 
@@ -62,6 +62,7 @@ fp surfaces --project stowzilla --json
 fp surfaces show <key> --project stowzilla
 fp surfaces add <key> --project stowzilla [--name "..."] [--kind api|web|android|ios|other] [--audience ...] [--repo org/repo] [--default-branch main]
 fp surfaces edit <key> --project stowzilla [--name "..."] [--kind ...] [--audience ...] [--repo ...] [--default-branch ...] [--key new_key]
+fp surfaces edit <key> --project stowzilla [--showroom-url URL] [--showroom-label "..."] [--showroom-instructions "..." | --showroom-instructions-file PATH]
 fp surfaces delete <key> --project stowzilla [--yes]
 ```
 
@@ -74,6 +75,42 @@ A surface that requirements still require can't be deleted or re-keyed — the s
 refuses and names them. Taking a surface off a requirement is a human's call, so ask
 one rather than working around it.
 
+### fp showroom
+
+The client showroom is the one page a client of the project sees: the project's
+welcome note, then a card per surface with a link, a button label, and instructions
+for signing in and trying it. The team's agents keep that content; this command
+shows the result.
+
+```bash
+fp showroom --project stowzilla          # what a client sees, plus which surfaces are hidden and why
+fp showroom --project stowzilla --json   # { showroom, hidden, share_link }
+```
+
+Writing the content:
+
+```bash
+fp projects edit stowzilla --showroom-welcome "Hi Sam, here's what we built."
+fp projects edit stowzilla --showroom-welcome-file docs/showroom/welcome.txt
+fp surfaces edit web --project stowzilla \
+  --showroom-url https://dev.example.com \
+  --showroom-label "Open the web app" \
+  --showroom-instructions-file docs/showroom/web.txt
+fp surfaces edit ios --project stowzilla --showroom-url "" --showroom-instructions ""   # take the card down
+```
+
+A surface is on the showroom once it has a link or instructions, and leaves it when
+both are blank; there is no separate on/off switch, so `fp showroom` lists the hidden
+surfaces so a card that dropped out is noticed. Links must be `http://` or `https://`
+(the CLI checks before sending). The `-file` variants are for anything longer than a
+line: the showroom keeps line breaks, so write real paragraphs. Only the flags you pass
+are sent.
+
+Two things are deliberately not available to an agent's key: leaving feedback (that is
+the client talking) and turning the share link on or off (publishing a link anyone can
+open is a person's decision). `fp showroom` reports the share link as `unknown` for
+that reason; a human checks it under Project Settings → Showroom in the web app.
+
 ### fp list
 
 List requirements.