featureparity 0.0.21 → 0.0.23

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,

data/lib/fp/commands/comment.rb

@@ -19,6 +19,16 @@ module Fp
 
       VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
 
+      help_summary "Comment on a requirement's open change proposal"
+      help_usage 'fp comment <slug> --body "..." --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :body, 'The comment text', required: true
+      help_flag :change, 'Target a specific change id (defaults to the open proposal)'
+      help_flag :source_type, "Origin type: #{VALID_SOURCE_TYPES.join(', ')}"
+      help_flag :source_url, 'Origin URL'
+      help_flag :source_context, 'Free-form origin note'
+      help_example 'fp comment print_qr --body "This conflicts with the freezer label requirement" --project stowzilla'
+
       def run(args)
         opts, positional = parse_flags(args, KNOWN_FLAGS)
         require_project!(opts)

data/lib/fp/commands/config_cmd.rb

@@ -5,6 +5,15 @@ module Fp
     # fp config get|set|unset|list
     # Manage global CLI settings (stored in ~/.config/fp/config.yml)
     class ConfigCmd < Base
+      help_summary 'Manage global CLI settings (stored in ~/.config/fp/config.yml)'
+      help_usage 'fp config set <key> <value>',
+                 'fp config get <key>',
+                 'fp config unset <key>',
+                 'fp config list'
+      help_example 'fp config set api_url https://api.featureparity.dev'
+      help_example 'fp config list'
+      help_note "Allowed settings: api_url. 'fp config whoami' is an alias for 'fp whoami'."
+
       ALLOWED_SETTINGS = %w[api_url].freeze
 
       def run(args)

data/lib/fp/commands/conversation.rb

@@ -17,6 +17,11 @@ module Fp
     #   4. Agent runs `fp conversation <id>` to read the full context
     #   5. Agent implements based on Pari's suggestions
     class Conversation < Base
+      help_summary 'Read a Pari conversation so an agent can review AI suggestions'
+      help_usage 'fp conversation <conversation-id>'
+      help_example 'fp conversation 03h0abc123xyz'
+      help_note 'No --project needed; works for project and account-level conversations.'
+
       def run(args)
         _opts, positional = parse_flags(args)
         conversation_id = positional.first

data/lib/fp/commands/export.rb

@@ -11,6 +11,16 @@ module Fp
     # attached to a release as a point-in-time record of what the product is
     # supposed to do.
     class Export < Base
+      help_summary 'Export all requirements as a single Markdown document'
+      help_usage 'fp export --project <slug> [--status S] [--category C] [--surface X] [--output FILE]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :status, 'Only requirements with this status'
+      help_flag :category, 'Only requirements in this category'
+      help_flag :surface, 'Only requirements that name this surface'
+      help_flag :output, 'Write to this file instead of stdout'
+      help_example 'fp export --project stowzilla > requirements.md'
+      help_example 'fp export --project stowzilla --status active --surface customer_android --output reqs.md'
+
       KNOWN_FLAGS = {
         project: :string,
         status: :string,

data/lib/fp/commands/help.rb

@@ -2,37 +2,70 @@
 
 module Fp
   module Commands
-    # fp help
+    # fp help [<command>]
+    #
+    # With no argument, prints the top-level usage. With a command name, prints that
+    # command's own help — the same page `fp <command> --help` shows (Fizzy #1489).
     class Help < Base
-      def run(_args)
+      def run(args)
+        topic = args.first
+        if topic && Fp::CLI::COMMANDS.key?(topic)
+          puts Fp::CLI::COMMANDS[topic].help_text(topic)
+          return
+        end
+
+        if topic && !topic.start_with?('-')
+          output.error("Unknown command: #{topic}") if output
+          warn "Unknown command: #{topic}" unless output
+          puts "\nRun 'fp help' for the list of commands."
+          return
+        end
+
+        print_overview
+      end
+
+      private
+
+      def print_overview
         puts <<~HELP
           fp - FeatureParity CLI for agents
 
           USAGE
             fp <command> [flags]
+            fp <command> --help               Show a command's own usage and flags
+            fp <command> --help --json        ...as a machine-readable flag schema
+            fp help <command>                 Same, spelled the other way
+            fp --version                      Show the installed version (alias: -v)
 
           COMMANDS
             init --project <slug>             Onboard this repo: config, CI gate, agent docs
             projects                          List projects you have access to
             projects show <slug>              View a project and its surfaces
             projects create <slug> --name ... Create a project (owned by your key's owner)
-            projects edit <slug> --name ...   Update a project's name or description
+            projects edit <slug> --name ...   Update a project's name, description, or showroom welcome
             projects delete <slug> [--yes]    Delete a project (asks you to type its slug)
             surfaces --project <slug>         List surfaces for a project
             surfaces show <key> --project ... View a single surface's details
             surfaces add <key> --project ...  Create a surface
-            surfaces edit <key> --project ... Change a surface (name, kind, repo, key...)
+            surfaces edit <key> --project ... Change a surface (name, kind, repo, key, showroom card...)
             surfaces delete <key> --project . Delete a surface (asks first; --yes to skip)
+            showroom --project <slug>         Preview the client showroom as a client sees it
+            showroom media --project <slug>   List the showroom's screenshots and videos
+            showroom media add <file> ...     Add an image/video to a surface card (--surface) or the gallery
+            showroom media edit <id> ...      Change a media item's --caption or --position
+            showroom media remove <id> --yes  Take a media item off the showroom
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
             propose-change <slug> ...         Propose a change to an existing requirement
             propose-change <slug> --removal   Propose deleting a requirement
+            propose-change <slug> --no-parent Propose un-nesting a child to top level
+            propose-change <slug> --withdraw  Withdraw your own open proposal (to amend it)
             comment <slug> --body "..."       Comment on a requirement's open change proposal
             history <slug> --project <slug>   Show a requirement's change history + diffs
             analyze [<slug>] --project <slug> Triage requirement quality (read-only; never proposes)
             changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
-            attach <slug> <file>              Upload a file attachment to a requirement
+            attach <slug> <file> [<file>...]  Upload one or more file attachments to a requirement
             attachments <slug>                List attachments for a requirement
             attachments <slug> <id>           Get download URL for an attachment
             attach rm <slug> <id>             Delete an attachment
@@ -51,7 +84,7 @@ module Fp
             whoami                            Show the resolved config (profile, env, API URL, key)
             repos set|get|list|unset          Map surfaces to local repo paths
             setup                             Interactive first-time setup
-            version                           Show version
+            version                           Show version (also: fp --version, fp -v)
             help                              Show this help
 
           GLOBAL FLAGS
@@ -66,6 +99,27 @@ module Fp
             so a checkout declares its own project once instead of every CI job and agent
             repeating it. `fp init` writes that file.
 
+          CLIENT SHOWROOM
+            The showroom is the one page a client sees: a welcome note, then a card per
+            surface with a link, a button label, and sign-in instructions. The team's
+            agents keep that content, because the agent that deployed a surface and made
+            its demo accounts is the one that knows the URL and the credentials:
+
+              fp projects edit <slug> --showroom-welcome "Hi Sam, here's what we built." \\
+                                      # or --showroom-welcome-file welcome.txt
+              fp surfaces edit web --showroom-url https://dev.example.com \\
+                                   --showroom-label "Open the web app" \\
+                                   --showroom-instructions-file docs/showroom/web.txt
+              fp showroom media add e2e/checkout.webm --surface web --caption "Checking out"
+              fp showroom media add overview.png   # no --surface: the gallery under the welcome
+              fp showroom          # what the client will see, and which surfaces are hidden
+
+            A surface is shown once it has a link, instructions, or media; pass an empty
+            value to clear a field (`--showroom-url ""`) and a surface with none drops out.
+            Media is images and video only (png, jpg, gif, webp, mp4, webm, mov; 100 MB).
+            Leaving feedback and turning the share link on or off are for humans, in the
+            web app under Project Settings → Showroom.
+
           ENFORCEMENT
             `fp check` fails a build when the project violates its enforcement level. Make it
             a required status check on your default branch to block merges.
@@ -287,6 +341,15 @@ module Fp
               --removal \\
               --reason "Superseded by print_container_label"
 
+            # Un-nest a child back to the top level (clears its parent)
+            fp propose-change print_container_qr_ios --project stowzilla --no-parent \\
+              --reason "Promoted to a top-level promise"
+
+            # Amend a proposal you already opened: the single-open-proposal rule won't let
+            # you open a second, so withdraw yours (restoring the requirement) and propose
+            # again. Only the author can withdraw; someone else's proposal goes to review.
+            fp propose-change print_container_qr --project stowzilla --withdraw
+
             # See what changed, why, and who asked for it
             fp history print_container_qr --project stowzilla
             fp history print_container_qr --project stowzilla --pending
@@ -357,6 +420,18 @@ module Fp
               --work-item https://app.fizzy.do/123/cards/456
             # --base-dir sets where relative test file paths in the report resolve from
             # Skipped tests are reported as 'stub'; everything else as 'present'.
+            # --test-type sets the kind of test (unit, e2e, ...) for markers that pin
+            # none. Give a different suite (e.g. a Playwright e2e run) its own type, or
+            # evidence for the same requirement+surface collides on the 'unspecified'
+            # bucket and the last report silently overwrites the earlier ones.
+
+            # Playwright's JUnit reporter is understood natively: titles joined with
+            # › (or :: for pytest-style ids) bind by name, a classname relative to the
+            # runner's testDir is searched for under base-dir, and --attach-media uploads
+            # the videos/screenshots the run recorded ([[ATTACHMENT|…]]) as visual
+            # evidence, each nested under the test it proves.
+            fp report --junit junit.xml --project stowzilla \\
+              --surface web --repo stowzilla/app --base-dir frontend --attach-media
 
             # CI ONLY: ingest real pass/fail results. Run in your CI pipeline after
             # the suite (on green AND red builds). Unlike `fp report`, this writes

data/lib/fp/commands/history.rb

@@ -9,6 +9,14 @@ module Fp
     # proposal, if there is one, is called out at the end because that's the thing
     # someone still has to decide on.
     class History < Base
+      help_summary "A requirement's change history: what changed, who changed it, and why"
+      help_usage 'fp history <slug> --project <slug> [--pending] [--limit N]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :pending, 'Show only the open proposal, if any'
+      help_flag :limit, 'Cap the number of events shown'
+      help_example 'fp history print_container_qr --project stowzilla'
+      help_example 'fp history print_container_qr --project stowzilla --pending'
+
       KNOWN_FLAGS = { project: :string, pending: :boolean, limit: :string }.freeze
 
       # Human labels for event types. The wire values are stable identifiers; these are

data/lib/fp/commands/init.rb

@@ -23,6 +23,19 @@ module Fp
     # unless --force, and the AGENTS.md section is appended once and detected by a
     # marker comment on re-run.
     class Init < Base
+      help_summary 'Onboard a repo: write .featureparity.yml, a CI gate workflow, and agent docs'
+      help_usage 'fp init --project <slug> [--surface X] [--level L] [--dir PATH] [--force]'
+      help_flag :project, 'Project slug to record in .featureparity.yml', required: true
+      help_flag :surface, 'Default surface for this (single-surface) repo'
+      help_flag :level, 'Enforcement level to record (usually omit and let the project decide)'
+      help_flag :dir, 'Target directory (defaults to the working directory)'
+      help_flag :force, 'Refresh files fp previously wrote'
+      help_flag :no_workflow, 'Skip writing the CI workflow'
+      help_flag :no_agents, 'Skip appending the AGENTS.md section'
+      help_example 'fp init --project stowzilla --surface api'
+      help_example 'fp init --project stowzilla --no-workflow'
+      help_note 'Makes no API calls, so a repo can be onboarded before anyone has a key.'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
@@ -174,6 +187,9 @@ module Fp
           puts '  2. Add the FP_API_KEY secret to the repo so CI can report evidence and run the gate.'
           puts "  3. Try the gate locally:  fp check#{opts[:surface] ? " --surface #{opts[:surface]}" : ''}"
           puts
+          puts 'Until the FP_API_KEY secret is added, the gate skips with an explanation'
+          puts 'instead of failing — so the first push that onboards the repo stays green.'
+          puts
           puts 'The gate starts at the `regression` level, which only fails on tests that have'
           puts 'gone red — it will not block you on requirements that were never covered. Raise'
           puts 'the level to `covered` or `strict` once the gaps are paid down.'
@@ -218,6 +234,13 @@ module Fp
               permissions:
                 contents: read
                 pull-requests: write
+              # Whether the FP_API_KEY secret exists on this repo. Every step that talks
+              # to FeatureParity is guarded on this, so the very first push — before
+              # anyone has added the secret — explains what to do instead of dying with a
+              # bare "No API key found" from fp. Fork pull requests also can't read the
+              # secret, and are skipped the same way.
+              env:
+                HAVE_FP_KEY: ${{ secrets.FP_API_KEY != '' }}
               steps:
                 - uses: actions/checkout@v4
 
@@ -228,8 +251,30 @@ module Fp
                 - name: Install fp
                   run: gem install featureparity
 
+                # Without the secret there is nothing the gate can do yet, so say so
+                # clearly (in the job summary and the log) and let the build pass. This is
+                # the expected state right after `fp init`: the repo is onboarded, the
+                # maintainer just hasn't added the key. A green, explanatory run beats a
+                # red one nobody can action.
+                - name: FeatureParity not configured yet
+                  if: env.HAVE_FP_KEY != 'true'
+                  run: |
+                    {
+                      echo '## FeatureParity gate skipped'
+                      echo ''
+                      echo 'The `FP_API_KEY` secret is not set on this repository, so the parity'
+                      echo 'gate cannot run yet. This is expected on the first push after `fp init`.'
+                      echo ''
+                      echo 'To enable the gate, add a repository secret named `FP_API_KEY`'
+                      echo '(Settings → Secrets and variables → Actions → New repository secret).'
+                      echo 'Mint a key at https://featureparity.dev (Account → Agents & API keys).'
+                      echo ''
+                      echo 'Fork pull requests cannot read the secret and will always show this.'
+                    } >> "$GITHUB_STEP_SUMMARY"
+                    echo 'FP_API_KEY is not set — skipping the parity gate. See the job summary.'
+
                 - name: Update PR requirement changes
-                  if: github.event_name == 'pull_request'
+                  if: github.event_name == 'pull_request' && env.HAVE_FP_KEY == 'true'
                   env:
                     FP_API_KEY: ${{ secrets.FP_API_KEY }}
                     GITHUB_TOKEN: ${{ github.token }}
@@ -247,6 +292,9 @@ module Fp
                 # Add `--warn-only` while adopting if you need the annotations without
                 # blocking merges yet.
                 #
+                # Guarded on HAVE_FP_KEY so a repo that hasn't added the secret yet gets
+                # the explanatory step above instead of a bare "No API key found" failure.
+                #
                 # NOTE: as written this gates on what has been *recorded*, which on a pull
                 # request is the default branch's state. To judge a branch on its own
                 # results, emit JUnit in this job and pass it — nothing is saved:
@@ -258,6 +306,7 @@ module Fp
                 # suite stays green while the requirement loses its only proof. Use one
                 # call per surface.
                 - name: Check parity
+                  if: env.HAVE_FP_KEY == 'true'
                   env:
                     FP_API_KEY: ${{ secrets.FP_API_KEY }}
                   run: fp check

data/lib/fp/commands/list.rb

@@ -5,6 +5,18 @@ module Fp
     # fp list --project <slug> [--surface X] [--category Y] [--gaps] [--status draft]
     # List requirements, optionally filtered
     class List < Base
+      help_summary 'List requirements, optionally filtered'
+      help_usage 'fp list --project <slug> [--surface X] [--category Y] [--tag Z] [--status S] [--gaps]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Only requirements that name this surface'
+      help_flag :category, 'Filter by category'
+      help_flag :tag, 'Filter by a free-form tag'
+      help_flag :status, 'Filter by status: active (default), draft, archived'
+      help_flag :gaps, 'Show only requirements with an uncovered required surface (reads evidence)'
+      help_example 'fp list --project stowzilla'
+      help_example 'fp list --project stowzilla --status draft', 'Drafts are hidden by default'
+      help_example 'fp list --project stowzilla --gaps --surface customer_android'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,

data/lib/fp/commands/matrix.rb

@@ -13,6 +13,15 @@ module Fp
     # parity report, which is the same computation the CI gate blocks on, so what you
     # see here is what CI will decide.
     class Matrix < Base
+      help_summary 'Show the parity matrix (requirements × surfaces with evidence state)'
+      help_usage 'fp matrix --project <slug> [--surface api] [--level covered] [--csv]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Limit to one surface'
+      help_flag :level, 'Evaluate against this enforcement level (off/regression/covered/strict)'
+      help_flag :csv, 'Emit CSV instead of the ASCII table'
+      help_example 'fp matrix --project stowzilla'
+      help_example 'fp matrix --project stowzilla --csv > matrix.csv'
+
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,

data/lib/fp/commands/profile.rb

@@ -5,6 +5,15 @@ module Fp
     # fp profile add|list
     # Manage named profiles for API authentication
     class Profile < Base
+      help_summary 'Manage named authentication profiles'
+      help_usage 'fp profile add <name> --api-key fp_... [--api-url URL] [--environment ENV]',
+                 'fp profile list'
+      help_flag :api_key, 'API key for the profile (starts with fp_)'
+      help_flag :api_url, 'Override API URL for the profile'
+      help_flag :environment, 'Named environment for the profile'
+      help_example 'fp profile add pari --api-key fp_...'
+      help_example 'fp --profile pari projects'
+
       KNOWN_FLAGS = {
         api_key: :string,
         api_url: :string,

data/lib/fp/commands/projects.rb

@@ -17,7 +17,27 @@ module Fp
     # or takes --yes to skip the prompt, and a non-interactive session without --yes is
     # refused rather than guessed at. The server adds its own check — only an owner (or an
     # owner's key) may delete.
+    #
+    # `edit --showroom-welcome` keeps the note at the top of the client showroom (Fizzy
+    # #1479); the per-surface cards are `fp surfaces edit --showroom-*`, and `fp showroom`
+    # previews the result.
     class Projects < Base
+      help_summary 'List, view, create, edit, and delete projects'
+      help_usage 'fp projects',
+                 'fp projects show <slug>',
+                 'fp projects create <slug> --name "..." [--description ...] [--surfaces a,b,c]',
+                 'fp projects edit <slug> [--name ...] [--description ...]',
+                 'fp projects delete <slug> [--yes]'
+      help_flag :name, 'Project name (create/edit)'
+      help_flag :description, 'Project description (create/edit)'
+      help_flag :showroom_welcome, 'Welcome note at the top of the client showroom (edit; empty clears)'
+      help_flag :showroom_welcome_file, 'Read --showroom-welcome from a file (multi-line)'
+      help_flag :surfaces, 'Comma-separated surface keys to create with the project'
+      help_flag :yes, 'Skip the typed-slug confirmation on delete'
+      help_example 'fp projects create calib-rate --name "Calib Rate" --surfaces api,web'
+      help_example 'fp projects delete calib-rate --yes'
+      help_note 'Projects land on the key owner\'s account; the same key reaches them immediately. Delete is owner-only.'
+
       CREATE_FLAGS = {
         name: :string,
         description: :string,
@@ -26,7 +46,9 @@ module Fp
 
       EDIT_FLAGS = {
         name: :string,
-        description: :string
+        description: :string,
+        showroom_welcome: :string,
+        showroom_welcome_file: :string
       }.freeze
 
       DELETE_FLAGS = {
@@ -135,14 +157,17 @@ module Fp
 
       def edit(args)
         opts, positional = parse_flags(args, EDIT_FLAGS)
-        slug = require_slug!(positional, 'fp projects edit <slug> [--name "..."] [--description "..."]')
+        slug = require_slug!(positional, 'fp projects edit <slug> [--name "..."] [--description "..."] ' \
+                                         '[--showroom-welcome "..." | --showroom-welcome-file PATH]')
 
         params = {}
         params[:name] = opts[:name] if opts[:name]
         params[:description] = opts[:description] if opts.key?(:description)
+        welcome = showroom_welcome_param(opts)
+        params[:showroom_welcome] = welcome unless welcome.nil?
 
         if params.empty?
-          output.error('Nothing to change. Pass --name and/or --description.')
+          output.error('Nothing to change. Pass --name, --description, --showroom-welcome, or --showroom-welcome-file.')
           exit 1
         end
 
@@ -161,9 +186,40 @@ module Fp
           puts
           puts "  Name:        #{record['name']}"
           puts "  Description: #{blank?(record['description']) ? '(none)' : record['description']}"
+          if params.key?(:showroom_welcome)
+            puts "  Showroom welcome: #{blank?(record['showroom_welcome']) ? '(cleared)' : ''}"
+            record['showroom_welcome'].to_s.each_line { |line| puts "    #{line.rstrip}" }
+          end
         end
       end
 
+      # The welcome note from --showroom-welcome or --showroom-welcome-file, nil when
+      # neither was passed. An empty value clears the note. A file is the sane way to
+      # write several paragraphs; the showroom keeps the line breaks.
+      def showroom_welcome_param(opts)
+        if opts.key?(:showroom_welcome) && opts.key?(:showroom_welcome_file)
+          output.error('Pass --showroom-welcome or --showroom-welcome-file, not both.')
+          exit 1
+        end
+
+        if opts.key?(:showroom_welcome_file)
+          path = opts[:showroom_welcome_file]
+          if path == true || path.to_s.strip.empty?
+            output.error('--showroom-welcome-file needs a path')
+            exit 1
+          end
+          unless File.file?(path)
+            output.error("--showroom-welcome-file: no such file '#{path}'")
+            exit 1
+          end
+          return File.read(path).strip
+        end
+
+        return nil unless opts.key?(:showroom_welcome)
+
+        opts[:showroom_welcome] == true ? '' : opts[:showroom_welcome].to_s
+      end
+
       def delete(args)
         opts, positional = parse_flags(args, DELETE_FLAGS)
         slug = require_slug!(positional, 'fp projects delete <slug> [--yes]')
@@ -276,6 +332,10 @@ module Fp
         puts
         puts "Slug:         #{project['slug']}"
         puts "Description:  #{blank?(project['description']) ? '(none)' : project['description']}"
+        unless blank?(project['showroom_welcome'])
+          puts 'Showroom welcome:'
+          project['showroom_welcome'].to_s.each_line { |line| puts "  #{line.rstrip}" }
+        end
         puts "Enforcement:  #{project['enforcement_level']}" if project['enforcement_level']
         puts "Surfaces:     #{surfaces.empty? ? '(none)' : surfaces.join(', ')}"
 

data/lib/fp/commands/propose.rb

@@ -5,6 +5,24 @@ module Fp
     # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --required-types unit,e2e --acceptance "..." --parent <slug> --category <cat>
     # Create a new requirement as draft
     class Propose < Base
+      help_summary 'Propose a new requirement (created as a draft; a human activates it)'
+      help_usage 'fp propose --project <slug> --slug <key> --name "..." [flags]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :slug, 'Initial key for the requirement', required: true
+      help_flag :name, 'Human-readable title (one product promise, present tense)', required: true
+      help_flag :why, 'One or two sentences: who needs it, the problem, the outcome'
+      help_flag :acceptance, 'Observable result + boundaries a reviewer can check'
+      help_flag :required, 'Comma-separated surfaces this requirement must be covered on'
+      help_flag :required_types, "Comma-separated test kinds each surface needs (project's vocabulary)"
+      help_flag :parent, "Parent requirement's slug (nests one level; subset of parent's surfaces)"
+      help_flag :category, 'One of: functional, non-functional, ux, performance, security, compliance'
+      help_flag :tags, 'Comma-separated free-form labels'
+      help_flag :source_type, 'Where it came from: fizzy, discord, github_issue, jira, notion, manual, ai_chat'
+      help_flag :source_url, 'URL of the originating card/issue/thread'
+      help_flag :source_context, 'Free-form note about the origin'
+      help_example 'fp propose --project stowzilla --slug print_qr --name "Print QR on container label" --why "Staff mis-type the ID without a scannable code" --required api,customer_ios --acceptance "QR scans to the container detail page"'
+      help_note 'Agents can only create drafts. A human activates it in the web app.'
+
       KNOWN_FLAGS = {
         project: :string,
         slug: :string,