featureparity 0.0.14 → 0.0.16

data/lib/fp/commands/changes.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module Fp
+  module Commands
+    # `fp changes` lists requirement activity associated with a work item. In GitHub
+    # Actions it can discover source URLs from the pull request body, append a job
+    # summary, and keep a managed table in the pull request description itself.
+    class Changes < Base
+      PR_SECTION_BEGIN = '<!-- feature-parity:requirement-changes:begin -->'
+      PR_SECTION_END = '<!-- feature-parity:requirement-changes:end -->'
+
+      KNOWN_FLAGS = {
+        project: :string,
+        source_url: :string,
+        github_summary: :boolean,
+        github_pr: :boolean
+      }.freeze
+
+      TYPE_LABELS = {
+        'created' => 'Created',
+        'updated' => 'Edited',
+        'activated' => 'Activated',
+        'archived' => 'Archived',
+        'rejected' => 'Rejected',
+        'destroyed' => 'Deleted',
+        'change_proposed' => 'Modification proposed',
+        'removal_proposed' => 'Removal proposed',
+        'change_approved' => 'Change approved',
+        'change_rejected' => 'Change rejected'
+      }.freeze
+
+      def run(args)
+        explicit_urls, rest = extract_repeated(args, '--source-url')
+        opts, = parse_flags(rest, KNOWN_FLAGS)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        @github_pull_request = fetch_github_pull_request if opts[:github_pr]
+
+        source_urls = explicit_urls.map(&:strip).reject(&:empty?).uniq
+        source_urls = github_source_urls if source_urls.empty?
+
+        data = {
+          project: project_slug,
+          source_urls: source_urls,
+          requirement_changes: [],
+          source_detected: !source_urls.empty?
+        }
+
+        if source_urls.any?
+          project_id = resolve_project_id(project_slug)
+          data[:requirement_changes] = fetch_changes(project_id, source_urls)
+        end
+
+        markdown = render_markdown(data)
+        destinations = []
+
+        if opts[:github_summary]
+          append_github_summary(markdown)
+          destinations << ENV['GITHUB_STEP_SUMMARY']
+        end
+        if opts[:github_pr]
+          update_github_pull_request(markdown)
+          destinations << 'the pull request description'
+        end
+
+        output.success(data) do
+          if destinations.any?
+            puts "FeatureParity requirement-change table updated in #{destinations.join(' and ')}."
+          else
+            puts markdown
+          end
+        end
+      end
+
+      private
+
+      def fetch_changes(project_id, source_urls)
+        changes = []
+
+        source_urls.each do |source_url|
+          result = client.list_project_requirement_changes(project_id, source_url: source_url)
+          if [400, 403, 404].include?(result[:status].to_i) && result[:error].to_s.match?(/bad request|not found/i)
+            return legacy_changes(project_id, source_urls)
+          end
+
+          unless result[:ok]
+            output.error(result[:error], status: result[:status])
+            exit 1
+          end
+
+          changes.concat(result[:data]['requirement_changes'] || [])
+        end
+
+        collapse_to_latest_per_requirement(
+          changes.uniq { |change| change['id'] }
+                 .sort_by { |change| change['recorded_at'].to_s }
+                 .reverse
+        )
+      end
+
+      # Option A: one row per requirement. A requirement whose creation and a later
+      # modification proposal both trace to the same work item would otherwise appear
+      # twice, which reads as a duplicate. We keep only the most recent event per
+      # requirement, so the table answers "where does each requirement stand now?"
+      # rather than replaying its whole timeline (that lives in `fp history <slug>`).
+      def collapse_to_latest_per_requirement(changes)
+        changes.each_with_object({}) do |change, latest|
+          key = change['slug'] || change['requirement_path'] || change['id']
+          latest[key] ||= change
+        end.values
+      end
+
+      # Compatibility with an API that predates the project activity endpoint. This is
+      # especially useful while a CLI/API release is rolling out: requirements whose own
+      # source matches the work item, plus every open proposal, are inspected through the
+      # existing per-requirement history endpoint. Once the endpoint is deployed, its
+      # ProjectIndex also covers reviewed and deleted activity without this bounded scan.
+      def legacy_changes(project_id, source_urls)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirements = result[:data]['requirements'] || []
+        candidates = requirements.select do |requirement|
+          source_urls.include?(requirement['source_url']) || present?(requirement['pending_change_id'])
+        end
+
+        collapsed = candidates.flat_map do |requirement|
+          history = client.list_requirement_changes(requirement['id'])
+          next [] unless history[:ok]
+
+          (history[:data]['changes'] || []).filter_map do |change|
+            next unless source_urls.include?(change.dig('source', 'url'))
+
+            change.merge(
+              'slug' => requirement['slug'],
+              'title' => requirement['title'],
+              'requirement_status' => requirement['status'],
+              'requirement_path' => "/projects/#{project_id}/requirements/#{requirement['id']}",
+              'review_state' => change.dig('review', 'decision') || (change['pending'] ? 'pending' : requirement['status'])
+            )
+          end
+        end.uniq { |change| change['id'] }
+           .sort_by { |change| change['recorded_at'].to_s }
+           .reverse
+
+        collapse_to_latest_per_requirement(collapsed)
+      end
+
+      def github_source_urls
+        body = if @github_pull_request
+                 @github_pull_request.fetch('body', '').to_s
+               else
+                 github_event.dig('pull_request', 'body').to_s
+               end
+
+        body = body.sub(/#{Regexp.escape(PR_SECTION_BEGIN)}.*?#{Regexp.escape(PR_SECTION_END)}/m, '')
+
+        # Option B: explicit fp-source markers take precedence
+        explicit = body.scan(/fp-source:\s*(https?:\/\/\S+)/i).flatten.map { |url| clean_url(url) }
+        return explicit.uniq if explicit.any?
+
+        # Option A: heuristic detection of ticket-tracker URLs
+        URI.extract(body, %w[http https])
+           .map { |url| clean_url(url) }
+           .select { |url| work_item_url?(url) }
+           .uniq
+      end
+
+      def github_event
+        return @github_event if defined?(@github_event)
+
+        event_path = ENV['GITHUB_EVENT_PATH']
+        @github_event = if present?(event_path) && File.file?(event_path)
+                          JSON.parse(File.read(event_path))
+                        else
+                          {}
+                        end
+      rescue JSON::ParserError
+        @github_event = {}
+      end
+
+      def work_item_url?(url)
+        # Heuristic detection: accept URLs that look like ticket trackers.
+        # Matches paths containing common ticket-tracker segments.
+        url.match?(%r{
+          \Ahttps?://[^/]+           # scheme and host
+          (?:
+            .*/(?:issues|cards|browse|tickets|tasks|work[-_]?items?|bugs?|stories?|features?|pull|merge_requests?|issue|story|_workitems|channels|c|t)/[^\s/]+ |
+            .*/\d+(?:/|\z)           # any path ending in /123 or /123/
+          )
+        }xi)
+      end
+
+      def clean_url(url)
+        url.sub(/[)\]}>.,;:]+\z/, '')
+      end
+
+      def append_github_summary(markdown)
+        path = ENV['GITHUB_STEP_SUMMARY']
+        unless present?(path)
+          output.error('--github-summary requires GITHUB_STEP_SUMMARY (it is set automatically by GitHub Actions)')
+          exit 1
+        end
+
+        File.open(path, 'a') { |file| file.puts(markdown) }
+      end
+
+      def fetch_github_pull_request
+        token, uri = github_credentials
+        response = github_request(Net::HTTP::Get, uri, token)
+        fail_github_request!('read the pull request', response) unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        output.error('GitHub returned an invalid response while reading the pull request')
+        exit 1
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        output.error("Could not read the pull request from GitHub: #{e.message}")
+        exit 1
+      end
+
+      def update_github_pull_request(markdown)
+        current_body = @github_pull_request.fetch('body', '').to_s
+        updated_body = managed_pull_request_body(current_body, markdown)
+        return if updated_body == current_body
+
+        token, uri = github_credentials
+        response = github_request(Net::HTTP::Patch, uri, token, body: { body: updated_body })
+        fail_github_request!('update the pull request description', response) unless response.is_a?(Net::HTTPSuccess)
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        output.error("Could not update the pull request description on GitHub: #{e.message}")
+        exit 1
+      end
+
+      def managed_pull_request_body(body, markdown)
+        section = "#{PR_SECTION_BEGIN}\n#{markdown}\n#{PR_SECTION_END}"
+        begin_count = body.scan(PR_SECTION_BEGIN).length
+        end_count = body.scan(PR_SECTION_END).length
+
+        unless [begin_count, end_count].all? { |count| [0, 1].include?(count) } && begin_count == end_count
+          output.error('The pull request description has malformed or duplicate FeatureParity requirement-change markers')
+          exit 1
+        end
+
+        if begin_count == 1
+          body.sub(/#{Regexp.escape(PR_SECTION_BEGIN)}.*?#{Regexp.escape(PR_SECTION_END)}/m, section)
+        else
+          [body.rstrip, section].reject(&:empty?).join("\n\n") + "\n"
+        end
+      end
+
+      def github_credentials
+        token = ENV['GITHUB_TOKEN']
+        repository = ENV['GITHUB_REPOSITORY'].to_s
+        number = github_event.dig('pull_request', 'number') || github_event['number']
+
+        unless present?(token) && repository.match?(%r{\A[^/]+/[^/]+\z}) && number.to_i.positive?
+          output.error('--github-pr requires GITHUB_TOKEN, GITHUB_REPOSITORY, and a pull_request GITHUB_EVENT_PATH')
+          exit 1
+        end
+
+        owner, repo = repository.split('/', 2).map { |part| URI.encode_www_form_component(part) }
+        api_url = ENV.fetch('GITHUB_API_URL', 'https://api.github.com').sub(%r{/+\z}, '')
+        [token, URI.parse("#{api_url}/repos/#{owner}/#{repo}/pulls/#{number.to_i}")]
+      rescue URI::InvalidURIError
+        output.error('GITHUB_API_URL is not a valid URL')
+        exit 1
+      end
+
+      def github_request(request_class, uri, token, body: nil)
+        request = request_class.new(uri)
+        request['Accept'] = 'application/vnd.github+json'
+        request['Authorization'] = "Bearer #{token}"
+        request['User-Agent'] = 'featureparity-cli'
+        request['X-GitHub-Api-Version'] = '2022-11-28'
+        if body
+          request['Content-Type'] = 'application/json'
+          request.body = JSON.generate(body)
+        end
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          http.request(request)
+        end
+      end
+
+      def fail_github_request!(action, response)
+        details = JSON.parse(response.body).fetch('message', response.body.to_s)
+        output.error("GitHub could not #{action}: #{details}", status: response.code.to_i)
+        exit 1
+      rescue JSON::ParserError
+        output.error("GitHub could not #{action}: HTTP #{response.code}", status: response.code.to_i)
+        exit 1
+      end
+
+      def render_markdown(data)
+        lines = ['## FeatureParity requirement changes', '']
+
+        unless data[:source_detected]
+          lines << '⚠️ No work-item URL was found in the pull request description, so FeatureParity cannot determine which requirement activity belongs to this change.'
+          return lines.join("\n")
+        end
+
+        links = data[:source_urls].map { |url| "[#{markdown_escape(url)}](#{url})" }
+        lines << "Work item#{links.length == 1 ? '' : 's'}: #{links.join(', ')}"
+        lines << ''
+
+        changes = data[:requirement_changes]
+        if changes.empty?
+          lines << 'No requirement changes are recorded for the linked work item(s).'
+          return lines.join("\n")
+        end
+
+        lines << '| Requirement | Change | Review | Actor |'
+        lines << '| --- | --- | --- | --- |'
+        changes.each do |change|
+          lines << "| #{requirement_cell(change)} | #{TYPE_LABELS.fetch(change['type'], change['type'])} | " \
+                   "#{markdown_escape(change['review_state'] || change['requirement_status'] || '—')} | " \
+                   "#{markdown_escape(change['actor'] || '—')} |"
+        end
+        lines << ''
+        lines << '_Open the linked requirement to review its wording, diff, evidence, and decision state._'
+        lines.join("\n")
+      end
+
+      def requirement_cell(change)
+        slug = change['slug'] || 'unknown'
+        title = markdown_escape(change['title'] || slug)
+        path = change['requirement_path']
+        return title unless present?(path)
+
+        "[#{title}](#{web_base_url}#{path})"
+      end
+
+      def web_base_url
+        uri = URI.parse(config.api_url)
+        host = uri.host.to_s.sub(/\Aapi\./, '')
+        "#{uri.scheme || 'https'}://#{host}"
+      rescue URI::InvalidURIError
+        'https://featureparity.dev'
+      end
+
+      def markdown_escape(value)
+        value.to_s.gsub('|', '\\|').gsub("\n", ' ')
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/fp/commands/check.rb

@@ -39,6 +39,7 @@ module Fp
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
+        test_type: :string,
         level: :string,
         junit: :string,
         base_dir: :string,
@@ -126,7 +127,8 @@ module Fp
 
         results = junit_paths.flat_map do |path|
           testcases = Fp::JUnit.parse_file(path)
-          Fp::JUnit.ci_results(testcases, base_dir: base_dir, default_surface: surface)[:results]
+          Fp::JUnit.ci_results(testcases, base_dir: base_dir, default_surface: surface,
+                                          default_test_type: opts[:test_type])[:results]
         end
 
         if results.empty?
@@ -141,6 +143,7 @@ module Fp
           {
             slug: r.slug,
             surface: r.surface,
+            test_type: r.test_type,
             status: r.status,
             source_file: r.file,
             source_line: r.line,
@@ -219,15 +222,35 @@ module Fp
         return if violations.empty?
 
         puts "#{violations.size} violation(s):"
-        output.table(
-          %w[SLUG SURFACE STATE WHY],
-          violations.map do |v|
-            [v['slug'], v['surface'], "#{Parity.glyph(v['state'])} #{v['state']}", v['reason']]
-          end
-        )
+        # Show the TYPE column only when some requirement demands specific test types —
+        # otherwise it's an empty column of dashes on every project that doesn't use the
+        # feature.
+        if violations.any? { |v| presence(v['test_type']) }
+          output.table(
+            %w[SLUG SURFACE TYPE STATE WHY],
+            violations.map do |v|
+              [v['slug'], v['surface'], v['test_type'] || '—',
+               "#{Parity.glyph(v['state'])} #{v['state']}", v['reason']]
+            end
+          )
+        else
+          output.table(
+            %w[SLUG SURFACE STATE WHY],
+            violations.map do |v|
+              [v['slug'], v['surface'], "#{Parity.glyph(v['state'])} #{v['state']}", v['reason']]
+            end
+          )
+        end
         puts
       end
 
+      # nil/blank → nil, so `presence(x)` reads as falsey in a guard.
+      def presence(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        value
+      end
+
       # Markers the run carried that bind to no requirement in this project — the test
       # claims to cover something that doesn't exist. FP identifies them; it does not
       # propose the requirement, because a slug and a test name aren't enough to write a

data/lib/fp/commands/ci_report.rb

@@ -50,6 +50,7 @@ module Fp
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
+        test_type: :string,
         ci_url: :string,
         pr: :string,
         junit: :string,
@@ -214,7 +215,8 @@ module Fp
         resolved = Fp::JUnit.ci_results(
           testcases,
           base_dir: opts[:base_dir] || Dir.pwd,
-          default_surface: opts[:surface]
+          default_surface: opts[:surface],
+          default_test_type: opts[:test_type]
         )
 
         {
@@ -222,9 +224,11 @@ module Fp
             {
               slug: r.slug,
               surface: r.surface,
+              test_type: r.test_type,
               status: r.status,
               source_file: r.file,
               source_line: r.line,
+              title: r.title,
               test_count: r.test_count,
               failure_count: r.failure_count
             }

data/lib/fp/commands/conversation.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp conversation <conversation_id>
+    # Read a Pari conversation so agents can review AI suggestions and implement them.
+    #
+    # A conversation is just a record identified by its id — the command doesn't care,
+    # and doesn't ask, whether it came from a project panel or the account-level one.
+    # The server resolves the owner and authorizes the caller. That's the whole point:
+    # a user copies a reference, hands it to an agent, and the agent reads it.
+    #
+    # Typical workflow:
+    #   1. User opens Pari, has a conversation that suggests requirements or code
+    #   2. User clicks "Copy Reference" (or "Copy Prompt") to get the lookup command
+    #   3. User gives it to an agent: "implement what Pari suggested in <id>"
+    #   4. Agent runs `fp conversation <id>` to read the full context
+    #   5. Agent implements based on Pari's suggestions
+    class Conversation < Base
+      def run(args)
+        _opts, positional = parse_flags(args)
+        conversation_id = positional.first
+
+        unless conversation_id
+          output.error(<<~MSG.strip)
+            Conversation ID is required.
+
+            Usage:
+              fp conversation <id>    Read a Pari conversation
+
+            The conversation ID is a KSUID like "03h0abc123xyz...". Copy it from Pari's
+            header (the copy buttons next to the history icon), or use "Copy Reference"
+            to get this whole command ready to paste.
+          MSG
+          exit 1
+        end
+
+        result = client.get_conversation(conversation_id)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        conversation = result[:data]['conversation']
+        messages = result[:data]['messages'] || []
+
+        output.success(result[:data]) do
+          print_conversation(conversation, messages)
+        end
+      end
+
+      private
+
+      def print_conversation(conversation, messages)
+        title = conversation['title'] || 'Untitled conversation'
+        puts title
+        puts '=' * title.length
+        puts
+        puts "ID:       #{conversation['id']}"
+        puts "Project:  #{conversation['project_id']}" if conversation['project_id'].to_s != ''
+        puts "Status:   #{conversation['status']}"
+        puts "Created:  #{conversation['created_at']}"
+        puts "Updated:  #{conversation['updated_at']}"
+        puts
+
+        if messages.empty?
+          puts '(no messages)'
+        else
+          puts 'Messages:'
+          puts '-' * 40
+          messages.each_with_index do |msg, idx|
+            role = msg['role'] == 'user' ? 'USER' : 'PARI'
+            puts
+            puts "[#{idx + 1}] #{role}:"
+            puts msg['content']
+
+            # Show any requirements Pari created during this turn
+            created = msg['created_requirement_ids'] || []
+            unless created.empty?
+              puts
+              puts "  → Created draft requirement(s): #{created.join(', ')}"
+            end
+
+            puts
+            puts '-' * 40
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -23,6 +23,12 @@ module Fp
             propose-change <slug> ...         Propose a change to an existing requirement
             propose-change <slug> --removal   Propose deleting a requirement
             history <slug> --project <slug>   Show a requirement's change history + diffs
+            changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
+            attach <slug> <file>              Upload a file attachment 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
+            conversation <id>                 Read a Pari conversation for agent review
             report <slug> --project <slug>... Report evidence for a requirement
             report --junit <file> ...         Upload evidence from a JUnit XML report (no CI)
             ci-report --junit <file> ...      Ingest CI test results (passing/failing) — CI only
@@ -151,16 +157,45 @@ module Fp
             # Show a specific requirement
             fp show print_container_qr --project stowzilla
 
-            # Propose a new requirement (creates as draft)
+            # Propose a new requirement (creates as draft).
+            # A requirement records the current shared understanding, not a decree handed from
+            # product to engineering. Refine it through conversation with customers, domain
+            # experts, and builders. Humans decide value and priority; agents surface gaps,
+            # inconsistencies, alternatives, and useful splits. Prefer outcomes over feature lists.
+            # Use available evidence: what people attempt, abandon, actually use, and what
+            # experiments reveal. The first requested solution is input, not unquestionable scope.
+            # First inventory the whole request and check active AND draft requirements. Give
+            # each independently testable/failable product promise a focused requirement; use
+            # a parent plus children for a broad capability with distinct behaviours or policy.
+            # Record concrete decisions (prices, quotas, dates, roles, fallbacks) in acceptance,
+            # and propose changes to adjacent requirements the work makes inaccurate.
+            # Before adding or changing a promise, ask whether it and related active/draft
+            # requirements can both be true for the same user, state, and conditions. Treat a
+            # failing bound test or required requirement edit as a contradiction signal: decide
+            # which promise reflects product intent and record that decision with propose-change
+            # (or --removal). Never weaken the test or add a requirement around the conflict;
+            # ask a human if intent is unclear.
             #
-            # --why must be brief and actually explain why: whoever approves it should grasp
-            # in one read the user need or outcome the feature serves. Longer is fine when it
-            # earns its length; wordy is not. Avoid filler, and avoid describing HOW it works
-            # instead of WHY anyone wants it.
-            #   good: "Staff scan the label to find a container; without a QR they key the ID by hand and mis-type it."
-            #   bad:  "Ensures a high-quality experience across all surfaces." (filler)
-            # --acceptance is the observable condition that proves it's done, not a
-            # restatement of the title.
+            # Write the requirement as a product decision someone can approve, not a design
+            # task. It should sound like a capable teammate, not AI boilerplate.
+            #   title: one product promise in present tense, not the implementation project
+            #   why: one or two natural sentences naming the user need/problem and outcome
+            #   acceptance: trigger or situation + observable result + material boundaries
+            # Use examples and tests to ground and double-check the general rule, not to replace
+            # it or ongoing conversation. Leave out components, data models, algorithms, endpoints,
+            # and UI controls unless they are themselves part of the user-visible contract.
+            # Include a price, quota, timeout, count, date,
+            # role, or fallback only when the source made it a real product decision; if an
+            # important policy is missing, ask instead of inventing a plausible value.
+            #
+            #   good title:      "Dispatchers see current shipment status"
+            #   good why:        "Dispatchers need to spot delayed shipments before they miss a delivery window."
+            #   good acceptance: "When status changes, the dashboard shows it; when unavailable, it says so instead of showing stale data as current."
+            #   bad: "Implement Redis polling every 30 seconds to ensure a seamless experience."
+            #        (invented policy, implementation detail, and filler; no product outcome)
+            # Before saving, read it as a manager deciding scope: is the value clear, is the
+            # result observable, are decisions separated from guesses, and does every sentence
+            # earn its place?
             fp propose --project stowzilla \\
               --slug print_container_qr \\
               --name "Print QR code on container label" \\
@@ -182,6 +217,8 @@ module Fp
             # — the card, the thread, the issue. The requirement drops back to DRAFT and a
             # human reviews the old-vs-new diff before it counts again.
             fp propose-change print_container_qr --project stowzilla \\
+              --name "Print a scannable container QR" \\
+              --slug print_scannable_container_qr \\
               --why "Labels must survive a freezer" \\
               --acceptance "QR scans after 24h at -20C" \\
               --reason "Cold-chain rollout" \\
@@ -197,6 +234,25 @@ module Fp
             fp history print_container_qr --project stowzilla
             fp history print_container_qr --project stowzilla --pending
 
+            # Upload a file attachment to a requirement (screenshot evidence, docs, etc.)
+            # Supported formats: png, jpg, gif, webp, svg, pdf, txt, md (max 10 MB)
+            fp attach print_container_qr screenshot.png --project stowzilla
+
+            # List attachments for a requirement
+            fp attachments print_container_qr --project stowzilla
+
+            # Get a download URL for a specific attachment
+            fp attachments print_container_qr <attachment-id> --project stowzilla
+
+            # Delete an attachment
+            fp attach rm print_container_qr <attachment-id> --project stowzilla
+
+            # Read a Pari conversation so an agent can review AI suggestions.
+            # A conversation is just a record identified by its id — no --project
+            # needed, and it works for both project and account-level conversations.
+            # Use "Copy Reference" in Pari's header to get this command ready to paste.
+            fp conversation 03h0abc123xyz
+
             # Report evidence for a requirement
             fp report print_container_qr --project stowzilla \\
               --surface customer_android \\