From 4bfd4acd407b61a377e97ee39c9cf3f13368924f Mon Sep 17 00:00:00 2001
From: Federico Jaramillo Martinez <federico@klingit.com>
Date: Mon, 25 May 2026 14:26:22 +0200
Subject: [PATCH] docs: add persistent agent positioning

---
 .changeset/persistent-agent-manifesto.md |  5 ++
 docs/index.html                          | 26 +++++++++-
 docs/remote-first.html                   | 41 +++++++++++----
 docs/styles.css                          | 66 ++++++++++++++++++++++--
 4 files changed, 124 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/persistent-agent-manifesto.md

diff --git a/.changeset/persistent-agent-manifesto.md b/.changeset/persistent-agent-manifesto.md
new file mode 100644
index 0000000..5ab2107
--- /dev/null
+++ b/.changeset/persistent-agent-manifesto.md
@@ -0,0 +1,5 @@
+---
+"@jmfederico/pi-web": patch
+---
+
+Add homepage and remote-first website copy that explains PI WEB's persistent-by-default agent workflow.
diff --git a/docs/index.html b/docs/index.html
index bb6c453..2b3f718 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -6,12 +6,12 @@
     <title>PI WEB — persistent AI coding agents in your browser</title>
     <meta
       name="description"
-      content="PI WEB is a browser control plane for persistent Pi Coding Agent sessions running on your own machine or server."
+      content="PI WEB makes AI coding work persistent by default: agents keep running outside your browser while you supervise from any device."
     />
     <meta property="og:title" content="PI WEB" />
     <meta
       property="og:description"
-      content="Run AI coding agents in real workspaces, keep them alive, and control everything from a browser."
+      content="Run persistent AI coding agents in real workspaces, keep them alive outside your device, and supervise everything from a browser."
     />
     <meta property="og:image" content="assets/pi-web-banner.png" />
     <link rel="icon" type="image/svg+xml" href="assets/favicon.svg" />
@@ -121,6 +121,28 @@
         </div>
       </section>
 
+      <section class="section manifesto-section" aria-labelledby="manifesto-title">
+        <div class="container manifesto-panel">
+          <div class="manifesto-copy">
+            <p class="eyebrow"><span class="pulse"></span> The mental shift</p>
+            <h2 id="manifesto-title">Developer tools were built for a world that no longer exists.</h2>
+            <p>
+              Editors and terminals assume the work lives with you, on your device, inside your session. AI agents break
+              that assumption: their work should persist, continue, and evolve independently of your laptop.
+            </p>
+            <p>
+              PI WEB makes persistence first-class. Sessions live outside the browser, agents keep working, and every
+              device becomes a control surface for supervising, redirecting, and reviewing progress.
+            </p>
+          </div>
+          <div class="manifesto-lines" aria-label="PI WEB principles">
+            <p>Persistence should not be something you bolt on after the fact.</p>
+            <p>The work should not disappear the moment your session ends.</p>
+            <p>You do not carry the work. You guide it.</p>
+          </div>
+        </div>
+      </section>
+
       <section class="section">
         <div class="container">
           <div class="section-head">
diff --git a/docs/remote-first.html b/docs/remote-first.html
index 13b66db..c75f4dc 100644
--- a/docs/remote-first.html
+++ b/docs/remote-first.html
@@ -6,7 +6,7 @@
     <title>Remote-first development with PI WEB</title>
     <meta
       name="description"
-      content="Why PI WEB is built for remote AI-driven development with persistent agents and browser-based control."
+      content="Why PI WEB makes AI coding work persistent by default: agents keep running outside your device while the browser becomes the control plane."
     />
     <meta property="og:title" content="Remote-first development with PI WEB" />
     <meta property="og:image" content="assets/pi-web-banner.png" />
@@ -57,8 +57,8 @@
           <p class="eyebrow"><span class="pulse"></span> Remote-first development</p>
           <h1>Your laptop is a window, not the workstation.</h1>
           <p>
-            PI WEB is built around a simple shift: development should live where the work happens, not where your
-            current keyboard happens to be.
+            PI WEB is built around a simple shift: AI-driven development should live where the work can persist, not
+            where your current keyboard happens to be. You supervise the work; you do not have to host it.
           </p>
         </div>
       </section>
@@ -67,7 +67,8 @@
         <div class="container doc-layout">
           <aside class="toc" aria-label="Remote-first page contents">
             <strong>On this page</strong>
-            <a href="#why-local-blocks">Why local can block</a>
+            <a href="#why-local-blocks">The old assumption</a>
+            <a href="#persistence-first">Persistence first-class</a>
             <a href="#what-remote-unlocks">What remote unlocks</a>
             <a href="#browser-control">Browser as control plane</a>
             <a href="#human-role">The human role</a>
@@ -76,11 +77,14 @@
 
           <div class="doc-content">
             <section id="why-local-blocks">
-              <h2>Local-only development can become the blocker</h2>
+              <h2>Developer tools assumed the work lived locally</h2>
               <p>
-                Local development made sense when one human drove every keystroke from one machine. With AI agents, the
-                work can outlive the laptop session. Agents need stable repositories, shells, tools, secrets, build
-                caches, and time to keep running.
+                Editors and terminals were built around a simple assumption: the work lives with you, on your device,
+                inside your session. That made sense when one human drove every keystroke from one machine.
+              </p>
+              <p>
+                AI agents break that assumption. The work can outlive the laptop session, and agents need stable
+                repositories, shells, tools, secrets, build caches, and time to keep running.
               </p>
               <p>
                 When all of that is tied to a laptop, the laptop becomes the bottleneck: close the lid, change devices,
@@ -88,6 +92,21 @@
               </p>
             </section>
 
+            <section id="persistence-first">
+              <h2>Persistence should not be a workaround</h2>
+              <p>
+                Terminals are ephemeral by default. You can patch around that with tmux, screen, background processes,
+                and remote shells, but persistence is still something you bolt on after the fact.
+              </p>
+              <p>
+                PI WEB treats persistence as the foundation. Agent sessions live in a long-running runtime, workspaces
+                stay on the machine that runs the tools, and browser disconnects do not end the work.
+              </p>
+              <div class="callout manifesto-callout">
+                If AI is doing the work, the work should not be tied to your laptop.
+              </div>
+            </section>
+
             <section id="what-remote-unlocks">
               <h2>Remote AI-driven development unlocks persistent work</h2>
               <p>
@@ -121,7 +140,8 @@
                 while the development environment stays remote and stable.
               </p>
               <p>
-                Laptop, phone, tablet, desktop: they are just windows into the same running work.
+                Laptop, phone, tablet, desktop: they are just windows into the same running work. You remain in control,
+                but you are no longer the machine carrying the work.
               </p>
             </section>
 
@@ -132,6 +152,9 @@
                 environment and toward higher-leverage work: choosing direction, setting constraints, reviewing changes,
                 and deciding what ships.
               </p>
+              <p>
+                You do not carry the work. You guide it.
+              </p>
             </section>
 
             <section id="recommended-shape">
diff --git a/docs/styles.css b/docs/styles.css
index 45453af..681fedd 100644
--- a/docs/styles.css
+++ b/docs/styles.css
@@ -124,6 +124,7 @@ body::after {
   .home-page .title-context,
   .home-page .hero .eyebrow,
   .home-page .hero-lede,
+  .home-page .hero-manifesto,
   .home-page .hero-actions,
   .home-page .hero-stats,
   .home-page .terminal,
@@ -393,7 +394,8 @@ h1 {
 .callout,
 .toc,
 .code-card,
-.demo-frame {
+.demo-frame,
+.manifesto-panel {
   border: 1px solid var(--line);
   background: var(--panel);
 }
@@ -538,7 +540,8 @@ code .comment,
 .faq-item,
 .callout,
 .toc,
-.code-card {
+.code-card,
+.manifesto-panel {
   border-radius: var(--radius);
 }
 
@@ -600,6 +603,58 @@ code .comment,
   color: var(--muted);
 }
 
+.manifesto-section {
+  padding-top: 46px;
+}
+
+.manifesto-panel {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(280px, 0.58fr);
+  gap: 32px;
+  overflow: hidden;
+  padding: clamp(26px, 4vw, 38px);
+  border-left: 4px solid var(--brand-2);
+  background: var(--panel);
+}
+
+.manifesto-copy {
+  max-width: 760px;
+}
+
+.manifesto-copy h2 {
+  font-size: clamp(2.2rem, 4.6vw, 4rem);
+  line-height: 0.98;
+}
+
+.manifesto-copy p {
+  margin: 18px 0 0;
+  color: var(--muted);
+  font-size: 1.06rem;
+  line-height: 1.75;
+}
+
+.manifesto-lines {
+  display: grid;
+  align-content: end;
+  gap: 14px;
+}
+
+.manifesto-lines p {
+  margin: 0;
+  padding: 16px 18px;
+  border: 1px solid var(--line);
+  background: var(--panel-strong);
+  color: var(--text);
+  font-size: 1rem;
+  line-height: 1.55;
+}
+
+.manifesto-callout {
+  color: var(--text);
+  font-size: 1.08rem;
+  line-height: 1.65;
+}
+
 .install-panel {
   display: grid;
   grid-template-columns: minmax(0, 0.92fr) minmax(0, 1.08fr);
@@ -987,7 +1042,8 @@ html[data-theme="light"] .comment {
 @media (max-width: 920px) {
   .hero-grid,
   .install-panel,
-  .doc-layout {
+  .doc-layout,
+  .manifesto-panel {
     grid-template-columns: 1fr;
   }
 
@@ -1000,6 +1056,10 @@ html[data-theme="light"] .comment {
   .doc-grid {
     grid-template-columns: 1fr;
   }
+
+  .manifesto-lines {
+    align-content: start;
+  }
 }
 
 @media (max-width: 680px) {