From 9376154cb59c9b0adaee66a0ab28046bb1e05ef5 Mon Sep 17 00:00:00 2001
From: Hampton Lintorn-Catlin <hampton@squareup.com>
Date: Mon, 18 May 2026 15:30:34 -0500
Subject: [PATCH] Extract landing-page agents section into a swappable partial
 (COPLAN-3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The "Built for any AI agent" section on the landing page is the one piece
hosts most often want to customize: generic CoPlan tells users to read
/agent-instructions, but a deployment like coplan-square wants to tell its
users to run `sq agents skills add coplan` instead.

Rather than make hosts fork the entire landing page just to change that
paragraph (which is what `landing_page_partial` would force them to do),
expose a single config knob for just this section.

- Extract the agents section into _default_agents.html.erb
- Add CoPlan.configuration.landing_agents_partial, defaulting to it
- _default_landing.html.erb renders via the configured partial
- Add request specs for the default and the override path, asserting the
  rest of the landing page stays unchanged when only this section is swapped

Behavior is unchanged by default — the engine renders the same agents
paragraph it did before. Host-side change to actually use this hook will
ship in coplan-square in a follow-up.

Stacked on top of #113 (which introduced the landing page).

Amp-Thread-ID: https://ampcode.com/threads/T-019e22e9-1c86-71bc-a076-f5e6d06b03d0
Co-authored-by: Amp <amp@ampcode.com>
---
 .../coplan/welcome/_default_agents.html.erb   |  9 ++++
 .../coplan/welcome/_default_landing.html.erb  | 16 +++----
 engine/lib/coplan/configuration.rb            | 14 ++++++
 spec/requests/welcome_spec.rb                 | 46 +++++++++++++++++++
 4 files changed, 76 insertions(+), 9 deletions(-)
 create mode 100644 engine/app/views/coplan/welcome/_default_agents.html.erb

diff --git a/engine/app/views/coplan/welcome/_default_agents.html.erb b/engine/app/views/coplan/welcome/_default_agents.html.erb
new file mode 100644
index 0000000..6cb4be2
--- /dev/null
+++ b/engine/app/views/coplan/welcome/_default_agents.html.erb
@@ -0,0 +1,9 @@
+<section class="landing__agents">
+  <h2 class="landing__section-title">Built for any AI agent</h2>
+  <p>
+    CoPlan exposes a self-describing REST API at
+    <%= link_to "/agent-instructions", agent_instructions_path, class: "landing__inline-link" %>.
+    Point any AI agent — Amp, Claude Code, Cursor, your own — at it and it can create plans,
+    apply edits, and leave review comments on your behalf.
+  </p>
+</section>
diff --git a/engine/app/views/coplan/welcome/_default_landing.html.erb b/engine/app/views/coplan/welcome/_default_landing.html.erb
index 6e9dd36..c0a1619 100644
--- a/engine/app/views/coplan/welcome/_default_landing.html.erb
+++ b/engine/app/views/coplan/welcome/_default_landing.html.erb
@@ -51,15 +51,13 @@
     </div>
   </section>
 
-  <section class="landing__agents">
-    <h2 class="landing__section-title">Built for any AI agent</h2>
-    <p>
-      CoPlan exposes a self-describing REST API at
-      <%= link_to "/agent-instructions", agent_instructions_path, class: "landing__inline-link" %>.
-      Point any AI agent — Amp, Claude Code, Cursor, your own — at it and it can create plans,
-      apply edits, and leave review comments on your behalf.
-    </p>
-  </section>
+  <%# The agents section is the one piece of the landing page hosts most often
+      need to customize — generic CoPlan points at /agent-instructions, while
+      a deployment like coplan-square wants to tell its users to run
+      `sq agents skills add coplan` instead. Renders via configuration so a
+      host can swap this single section without forking the whole landing
+      page. See `CoPlan.configuration.landing_agents_partial`. %>
+  <%= render CoPlan.configuration.landing_agents_partial %>
 
   <% if signed_in? %>
     <footer class="landing__footer">
diff --git a/engine/lib/coplan/configuration.rb b/engine/lib/coplan/configuration.rb
index c1dcd25..514a779 100644
--- a/engine/lib/coplan/configuration.rb
+++ b/engine/lib/coplan/configuration.rb
@@ -18,6 +18,19 @@ class Configuration
     # The engine ships a generic default at "coplan/welcome/default_landing".
     attr_accessor :landing_page_partial
 
+    # Partial used to render the "Built for any AI agent" section of the
+    # landing page. This is the single piece of the landing page that hosts
+    # most often need to customize: the generic engine partial points users
+    # at `/agent-instructions`, while a deployment like coplan-square wants
+    # to tell its users to run `sq agents skills add coplan` instead.
+    #
+    # Swapping just this partial (rather than the whole landing page) lets
+    # hosts customize the agents callout without duplicating the hero, the
+    # how-it-works steps, or the CSS.
+    #
+    # The engine ships a generic default at "coplan/welcome/default_agents".
+    attr_accessor :landing_agents_partial
+
     # VAPID (Voluntary Application Server Identification) keys for Web Push.
     # Generate once with `bundle exec rails coplan:web_push:generate_keys`.
     # Public key is shared with the browser; private key signs push messages.
@@ -49,6 +62,7 @@ def initialize
       @agent_curl_prefix = 'curl -s -H "Authorization: Bearer $TOKEN"'
       @seed_plan_types = []
       @landing_page_partial = "coplan/welcome/default_landing"
+      @landing_agents_partial = "coplan/welcome/default_agents"
       @agent_auth_instructions = <<~MARKDOWN
         ## Authentication
 
diff --git a/spec/requests/welcome_spec.rb b/spec/requests/welcome_spec.rb
index d0eb40f..e381eb9 100644
--- a/spec/requests/welcome_spec.rb
+++ b/spec/requests/welcome_spec.rb
@@ -88,4 +88,50 @@
       expect(response.body).not_to include("Design docs, built for AI-assisted planning")
     end
   end
+
+  describe "landing_agents_partial configuration override" do
+    # The agents section is the one piece of the landing page we expect hosts
+    # to most often swap out (generic /agent-instructions vs deployment-
+    # specific install commands like `sq agents skills add coplan`). Verify
+    # the swap happens *and* that the rest of the landing page is untouched.
+
+    before { sign_in_as(bob) }
+
+    context "with the default partial" do
+      it "renders the generic agents section pointing at /agent-instructions" do
+        get welcome_path
+        expect(response.body).to include("Built for any AI agent")
+        expect(response.body).to include("/agent-instructions")
+      end
+    end
+
+    context "with a host-configured override" do
+      around do |ex|
+        original = CoPlan.configuration.landing_agents_partial
+        CoPlan.configuration.landing_agents_partial = "coplan/welcome/test_agents_override"
+        ex.run
+        CoPlan.configuration.landing_agents_partial = original
+      end
+
+      before do
+        view_path = CoPlan::Engine.root.join("app/views/coplan/welcome/_test_agents_override.html.erb")
+        File.write(view_path, "<section class=\"host-agents\">sq agents skills add coplan</section>\n")
+        @tmp_view = view_path
+      end
+
+      after { File.delete(@tmp_view) if @tmp_view&.exist? }
+
+      it "swaps the agents section while keeping the rest of the landing page" do
+        get welcome_path
+
+        # The host's agents copy is rendered…
+        expect(response.body).to include("sq agents skills add coplan")
+        # …the default agents copy is gone…
+        expect(response.body).not_to include("Built for any AI agent")
+        # …but the hero and how-it-works steps are still the engine defaults.
+        expect(response.body).to include("Design docs, built for AI-assisted planning")
+        expect(response.body).to include("How it works")
+      end
+    end
+  end
 end