fix onboarding setup flow

Author: calvin-archastro

.changeset/clean-readme-quickstart.md

@@ -0,0 +1,7 @@
+---
+"@archastro/redline": patch
+---
+
+Update the public setup flow for the live Chrome Web Store and default npm
+registry, and close the local pairing bridge automatically so Chrome-first
+onboarding continues in its original tab.

README.md

@@ -10,9 +10,6 @@ Redline combines a Chrome extension, a local helper, and an open agent skill.
 Select text on a page, leave the requested change in context, and ask your
 agent to pull it. Built by [ArchAstro](https://archastro.ai).
 
-> The Chrome Web Store submission is under review. npm 0.2.x uses the unpacked
-> extension workflow below; npm 0.3 and newer use Chrome Web Store pairing.
-
 ```
 [ Chrome extension ]  --local-->  [ Helper @ 127.0.0.1:7878 ]  --local-->  [ Coding agent ]
   select + comment                   private local state                    pull + act
@@ -34,44 +31,23 @@ Prerequisites: macOS or Linux, Node.js 18 or newer, Bash, curl, and jq, plus
 Chrome or another Chromium-based browser. Windows and Safari are not currently
 supported.
 
-### npm 0.2.x
-
-npm 0.2.x installs an unpacked extension:
-
-```bash
-npm install -g @archastro/redline --registry=https://registry.npmjs.org
-redline setup --with-screenshots
-redline start
-```
-
-Then open `chrome://extensions`, enable **Developer mode**, choose
-**Load unpacked**, and select `~/.redline/extension`.
-
-`--with-screenshots` enables Redline on normal HTTP/HTTPS pages and allows
-optional visible-page screenshots. Use `redline setup --local-only` for the
-lowest-permission localhost workflow.
-
-npm 0.2.x setup also installs or updates legacy Claude and Codex plugin state.
-npm 0.3 removes that side effect and replaces those plugins with the portable
-skill below.
-
-### npm 0.3+ and the Chrome Web Store
+1. [Install Redline from the Chrome Web Store](https://chromewebstore.google.com/detail/redline/bbllmeihbcmemadgmongicpklkjjgoaf).
+2. Install the CLI and portable agent skill:
 
-The Store listing is pending review:
-
-[Install Redline from the Chrome Web Store](https://chromewebstore.google.com/detail/redline/bbllmeihbcmemadgmongicpklkjjgoaf)
+   ```bash
+   npm install -g @archastro/redline
+   npx skills add ArchAstro/redline
+   ```
 
-Once the listing is available, install the extension and run:
+3. Start the local helper and pair the extension:
 
-```bash
-npm install -g @archastro/redline --registry=https://registry.npmjs.org
-npx skills add ArchAstro/redline
-redline setup
-```
+   ```bash
+   redline setup
+   ```
 
-The standard skills CLI owns skill installation and updates in npm 0.3+.
-Redline's 0.3+ CLI never installs, updates, removes, or inspects agent skills
-or legacy plugin state.
+The standard skills CLI owns skill installation and updates. Redline's CLI
+never installs, updates, removes, or inspects agent skills or legacy plugin
+state.
 
 `redline setup` starts the local helper and opens a short-lived consent page.
 Approve it to pair the extension with the local helper. No ArchAstro account
@@ -137,13 +113,9 @@ browser data.
 For a one-off setup without a global install:
 
 ```bash
-npx --yes --@archastro:registry=https://registry.npmjs.org \
-  --package @archastro/redline redline setup
+npx --yes --package @archastro/redline redline setup
 ```
 
-The explicit npm registry keeps setup working on machines that map the
-`@archastro` scope to a private package registry.
-
 ## Local-first data model
 
 Redline listens only on `127.0.0.1` and stores its state under `~/.redline` by

extension/background.js

@@ -212,6 +212,10 @@ function validConnectSender(msg, sender) {
     exactConnectUrl(sender.url) && exactConnectUrl(sender.tab.url);
 }
 
+async function returnToOnboarding(connectTabId) {
+  await chrome.tabs.remove(connectTabId);
+}
+
 class RedlineExtensionError extends Error {
   constructor(code, message) {
     super(message);
@@ -988,6 +992,11 @@ chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
           });
           await chrome.alarms.create(PAIRING_SECRET_ALARM, { when: Date.parse(msg.expires_at) });
         });
+        try {
+          await returnToOnboarding(sender.tab.id);
+        } catch {
+          // Pairing is staged even if the bridge tab closes during handoff.
+        }
         sendResponse({ ok: true, status: 'staged' });
         return;
       }

extension/onboarding.html

@@ -25,7 +25,7 @@ <h1 id="setup-title">Connect the local helper</h1>
         Checking for Redline on this computer...
       </p>
       <div id="setup-command" class="command-row">
-        <code>npx --yes @archastro/redline setup</code>
+        <code>npx --yes --package @archastro/redline redline setup</code>
         <button type="button" id="copy-command" class="secondary" title="Copy setup command">
           Copy
         </button>

extension/onboarding.js

@@ -2,7 +2,7 @@
   'use strict';
 
   const SECRET_KEY = 'redline_pairing_secret';
-  const SETUP_COMMAND = 'npx --yes @archastro/redline setup';
+  const SETUP_COMMAND = 'npx --yes --package @archastro/redline redline setup';
 
   function createOnboardingController({
     connectionClient, localStorage, sessionStorage, view, siteEnabler = null,
@@ -256,7 +256,7 @@
         disclosure.hidden = true;
         siteStep.hidden = true;
         declinedStep.hidden = true;
-        status.textContent = 'Run the setup command, then keep this page open.';
+        status.textContent = 'Run this once in Terminal. This page will continue automatically.';
       },
       showStatus(state) {
         const messages = {

package-lock.json

@@ -254,7 +254,7 @@ async function requestIsAuthorized(req) {
   return null;
 }
 
-const CONNECT_HTML = '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Connect Redline</title><body><main><h1>Connect Redline</h1><p>Open the Redline extension to review the local-data disclosure and finish connecting this Chrome profile.</p></main></body></html>';
+const CONNECT_HTML = '<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Connect Redline</title><body><main><h1>Connecting to Redline</h1><p>This secure handoff tab closes automatically. Continue in the Redline setup tab.</p></main></body></html>';
 
 const server = http.createServer(async (req, res) => {
   if (duplicateSecurityHeader(req)) {

runtime/server.js

@@ -584,7 +584,9 @@ test('packaged fragment reader rejects nonliteral pairing fragment spellings', (
   }
 });
 
-function fragmentBackground(localInitial = {}, devConfig, { failInjection = false, omitAccessApis = false } = {}) {
+function fragmentBackground(localInitial = {}, devConfig, {
+  failInjection = false, omitAccessApis = false,
+} = {}) {
   const session = memoryStorage();
   const local = memoryStorage(localInitial);
   const storageAccess = [];
@@ -628,6 +630,7 @@ function fragmentBackground(localInitial = {}, devConfig, { failInjection = fals
           }];
         },
         async create(details) { installEvents.push(['create', structuredClone(details)]); },
+        async remove(tabId) { installEvents.push(['remove', tabId]); },
         onUpdated: { addListener() {} },
         onRemoved: { addListener() {} },
       },
@@ -719,6 +722,9 @@ test('background stages a fragment secret only from the exact packaged top-frame
     'create', 'redline-pairing-secret-expiry',
     { when: Date.parse(background.session.data.redline_pairing_secret.expires_at) },
   ]);
+  assert.deepEqual(background.installEvents, [
+    ['remove', 17],
+  ]);
 
   const rejected = [
     [{ ...message, source: 'page-script' }, sender],

tests/extension-connection.test.js

@@ -681,9 +681,9 @@ test('extension-first onboarding exposes one exact copyable setup command and a
   const source = fs.readFileSync(ONBOARDING_PATH, 'utf8');
   const { SETUP_COMMAND, bindOnboardingPage } = require(ONBOARDING_PATH);
 
-  assert.equal(SETUP_COMMAND, 'npx --yes @archastro/redline setup');
+  assert.equal(SETUP_COMMAND, 'npx --yes --package @archastro/redline redline setup');
   assert.equal(html.split(SETUP_COMMAND).length - 1, 1);
-  assert.match(html, /<code>npx --yes @archastro\/redline setup<\/code>/);
+  assert.match(html, /<code>npx --yes --package @archastro\/redline redline setup<\/code>/);
   assert.match(html, /id="copy-command"[^>]+title="Copy setup command"/);
   assert.equal(typeof bindOnboardingPage, 'function');
   assert.match(source, /navigator\.clipboard\.writeText\(SETUP_COMMAND\)/);

tests/onboarding.test.js

@@ -136,7 +136,7 @@ test('README documents the portable skill and terminal invocation', () => {
   assert.match(read('skills/redline/SKILL.md'), /^name:\s*redline$/m);
 });
 
-test('public launch guidance distinguishes the current release from Store pairing', () => {
+test('public launch guidance uses the live Store pairing flow', () => {
   const readme = read('README.md');
   const security = read('SECURITY.md');
   const contributing = read('CONTRIBUTING.md');
@@ -145,12 +145,14 @@ test('public launch guidance distinguishes the current release from Store pairin
     encoding: 'utf8',
   });
 
-  assert.match(readme, /Chrome Web Store[^.]*under review/i);
-  assert.match(readme, /npm 0\.2\.x[^.]*unpacked extension/i);
-  assert.match(readme, /npm 0\.3[^.]*Chrome Web Store/i);
-  assert.match(readme, /0\.2\.x[^.]*Claude and Codex plugin state/i);
   assert.match(readme, /https:\/\/chromewebstore\.google\.com\/detail\/redline\/bbllmeihbcmemadgmongicpklkjjgoaf/);
+  assert.match(readme, /npm install -g @archastro\/redline/);
+  assert.match(readme, /npx skills add ArchAstro\/redline/);
+  assert.match(readme, /redline setup/);
   assert.match(readme, /pair[^.]*local helper/i);
+  assert.doesNotMatch(readme, /under review|pending review/i);
+  assert.doesNotMatch(readme, /npm 0\.2\.x/i);
+  assert.doesNotMatch(readme, /--registry|@archastro:registry/i);
   assert.doesNotMatch(readme, /command-line tools without an `Origin` header can access the sidecar locally/i);
   assert.match(security, /CLI credential/i);
   assert.match(security, /paired-browser credential/i);