From 6c576b24c2dc9bdd686f9208d715ecfc66b85cc8 Mon Sep 17 00:00:00 2001 From: myselfsiddharth Date: Fri, 28 Aug 2026 13:14:32 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20npx=20paragent=20works=20now=20?= =?UTF-8?q?=E2=80=94=20retire=20the=20"not=20published"=20caveats=20(#179)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit paragent@0.1.1 is on the registry with SLSA provenance, so three documents that were true this morning are now false. README: restore npx as the headline Quick Start and move the clone path back under the contributor
. Verified against the published tarball from a clean directory, not the working tree — `npx paragent record --fixture` writes a 6-step trajectory and `npx paragent compile` turns it into 6 rows, 3 pool-eligible, both exit 0. awesome-lists packet: the install-path precondition row and the "Ready to submit?" verdict both asserted `npm view paragent` returns 404. Flip them, and retire the #167 follow-up in Open questions. The verdict now says the mechanical preconditions are met while keeping the submission itself a founder decision — #138 reserves that, and whether a pre-gate project belongs on a curated list is unchanged by publishing. docs/README.md: the index row called the packet Blocked. Co-Authored-By: Claude Opus 5 --- README.md | 41 +++++++++++++-------------- docs/README.md | 2 +- docs/outreach/awesome-lists.md | 51 +++++++++++++++++++--------------- 3 files changed, 49 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index a098c78..90873c4 100644 --- a/README.md +++ b/README.md @@ -51,34 +51,22 @@ loudly at the step that broke, instead of silently completing the wrong task. ## Try it in 60 seconds -Clone, install, record against the bundled fixture, compile. No credentials and no -live site required for this path. - -> **`npx paragent` is not available yet.** The package is publishable (`bin`, `files`, -> `prepack`) but has not been published to the npm registry — `npm view paragent` -> returns 404. A tag-triggered release workflow lives in -> [`.github/workflows/release.yml`](.github/workflows/release.yml); cutting a release -> still needs an `NPM_TOKEN` repository secret (founder). Until then the clone path -> below is the only Quick Start that works. Tracked in -> [#167](https://github.com/DevToolie/Paragent/issues/167). +No clone, no credentials, no live site — a browser fixture ships inside the package. ```bash -git clone https://github.com/DevToolie/Paragent.git -cd Paragent -npm install npx playwright install chromium # one-time: the browser binary Playwright drives # 1. Record a login → dashboard-list trajectory against the bundled fixture # (the recorder serves it over loopback for the length of the recording) -npm run recorder -- --fixture --out trajectory.json +npx paragent record --fixture --out trajectory.json # 2. Compile it into a replayable bundle, one cache row per step -npm run compile -- --in trajectory.json --out bundle.json +npx paragent compile --in trajectory.json --out bundle.json ``` `npx playwright install chromium` is a separate step on purpose: it downloads a browser, and a package that pulls ~150 MB during `npm install` without asking is -a bad guest. Everything else works offline after install. +a bad guest. Everything else works offline. Replaying that bundle needs `host` and `port` bound to a server for the fixture pages — the same holes a recording against a real site carries. @@ -86,18 +74,29 @@ pages — the same holes a recording against a real site carries. Point the recorder at a real site instead: ```bash -npm run recorder -- --base-url http://127.0.0.1:3000 --headed +npx paragent record --base-url http://127.0.0.1:3000 --headed ``` Recorded values become parameter slots, so one recording covers a family of runs: ```bash -npm run recorder -- --fixture --dashboard-title "Q3 Latency" --series-count 5 +npx paragent record --fixture --dashboard-title "Q3 Latency" --series-count 5 +``` + +
+From a clone, if you want to contribute + +```bash +git clone https://github.com/DevToolie/Paragent.git +cd Paragent +npm install +npm run recorder -- --fixture --out trajectory.json +npm run compile -- --in trajectory.json --out bundle.json ``` -The npm scripts run the TypeScript sources through `tsx`. After -`npm run build`, the same CLI is also available as `node dist/src/cli.js …` -(the shape a future published `paragent` binary would ship). +The npm scripts run the TypeScript sources through `tsx`; the published package +ships compiled JavaScript and does not need it. +
Credentials are read from `PARAGENT_USERNAME` / `PARAGENT_USER_SECRET` and are never persisted to disk. Full command list: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). diff --git a/docs/README.md b/docs/README.md index 8a9e25b..4df1e38 100644 --- a/docs/README.md +++ b/docs/README.md @@ -159,7 +159,7 @@ Integrity surface: **[INTEGRITY-AUDIT.md](./INTEGRITY-AUDIT.md)**. | Doc | What it is | Status | Last true | Notes | | --- | --- | --- | --- | --- | -| [outreach/awesome-lists.md](outreach/awesome-lists.md) | Draft entries + preconditions for awesome-browser-automation and awesome-ai-agents | draft | 2026-08-21 | Issue #138. **Blocked** until #167 (honest Quick Start) or real npm publish; no external PRs from agents | +| [outreach/awesome-lists.md](outreach/awesome-lists.md) | Draft entries + preconditions for awesome-browser-automation and awesome-ai-agents | draft | 2026-08-28 | Issue #138. Preconditions **met** (`paragent@0.1.1` published, `npx` Quick Start verified); submission is still the founder's call, no external PRs from agents | --- diff --git a/docs/outreach/awesome-lists.md b/docs/outreach/awesome-lists.md index 2580c76..819de2e 100644 --- a/docs/outreach/awesome-lists.md +++ b/docs/outreach/awesome-lists.md @@ -4,7 +4,7 @@ doc_type: brief status: draft owner: D2 created: 2026-08-21 -updated: 2026-08-21 +updated: 2026-08-28 confidence: HIGH supersedes: null sources_verified: true @@ -13,12 +13,13 @@ sources_verified: true # Awesome-lists submission packet In-repo draft for [GitHub issue #138](https://github.com/DevToolie/Paragent/issues/138). -**Do not open external PRs from this packet** until a founder confirms the visitor -README is honest (see [#167](https://github.com/DevToolie/Paragent/issues/167)). -Awesome-list maintainers click through; a broken Quick Start is worse than no entry. +**Do not open external PRs from this packet** without explicit founder sign-off. +The honesty precondition that used to block this ([#167](https://github.com/DevToolie/Paragent/issues/167)) +is closed — the Quick Start now works — but awesome-list maintainers click through, and +submitting is a judgment call about scope and timing, not a checklist outcome. -Verified against this branch (`docs/138-awesome-lists`, based on `origin/main`) on -2026-08-21. +Preconditions re-verified against `origin/main` and the published `paragent@0.1.1` +tarball on 2026-08-28. --- @@ -27,34 +28,36 @@ Verified against this branch (`docs/138-awesome-lists`, based on `origin/main`) | Precondition | Issue status | Verified in repo | Status | | --- | --- | --- | --- | | Visitor README | **#133 MERGED** ([#133](https://github.com/DevToolie/Paragent/pull/133)) | Root `README.md` is a visitor landing page; internal map lives in [`docs/README-internal.md`](../README-internal.md) | **Done** | -| Install path / npm | **#134 CLOSED** (publishable work landed; see also [#155](https://github.com/DevToolie/Paragent/pull/155)) | `package.json` has `bin` / `files` / no `private: true`, but **`npm view paragent` → 404** — package is **not** on the registry. Root README Quick Start still documents `npx paragent …` | **Issue closed; publish missing.** Honest path waits on [#167](https://github.com/DevToolie/Paragent/issues/167) (clone Quick Start) and/or an actual publish | +| Install path / npm | **#134 CLOSED**; published by [#183](https://github.com/DevToolie/Paragent/pull/183) | `paragent@0.1.1` is on the registry with SLSA provenance. `npx paragent record --fixture` and `npx paragent compile` were run from a clean directory against the published tarball — both exit 0 and write their artifacts | **Done** | | Demo GIF | **#137 CLOSED** ([#140](https://github.com/DevToolie/Paragent/pull/140)) | [`docs/assets/demo.gif`](../assets/demo.gif) exists (~924 KB, 720×428) and is embedded in the root README | **Done** | The original #138 gate treated “#134 landed” as “visitor can install without cloning.” -That is **not** true today: publishable ≠ published. Treating the closed issue as green -would send list maintainers to a 404. +That gap — publishable ≠ published — is now closed: the package is on the registry and +the README documents the path that actually runs. --- ## Ready to submit? -**Verdict: blocked** until [#167](https://github.com/DevToolie/Paragent/issues/167) merges -(and this packet is re-checked), **or** until `paragent` is actually on npm and the -README `npx` path works from a clean machine. +**Verdict: the mechanical preconditions are met.** All three checklist rows are Done, +and the Quick Start a list maintainer would click through now works from a clean +machine — verified against the published tarball, not the working tree. -Rationale on this branch: +Rationale: -- Root README still instructs `npx paragent record …` / `npx paragent compile …`. -- `npm view paragent` returns 404. -- Submitting now advertises a Quick Start that fails for every stranger who tries it. +- `npm view paragent` returns `0.1.1` (was 404). +- Root README instructs `npx paragent record …` / `npx paragent compile …`, and both + commands run from the published package. +- The tarball carries an SLSA provenance attestation tying it to a GitHub Actions + build of this repo. -After #167 lands with a **clone-based** Quick Start that works, re-run this checklist. -A clone-only entry may then be acceptable to the founder even without npm; #138’s -original note that clone-only “reads as unfinished” remains a judgment call — do not -treat this packet as authorization to submit. +**This is still not authorization to submit.** #138 reserves the submission itself for +the founder, and two judgment calls remain open: whether a pre-gate project with no +Track-1 number belongs on a curated list at all, and whether the entry text below +clears the no-performance-claims constraint. Re-read both before opening anything. **Not in scope for agents on this task:** opening PRs to `angrykoala/awesome-browser-automation` -or `e2b-dev/awesome-ai-agents`. Founder submits after the README/#167 honesty gate. +or `e2b-dev/awesome-ai-agents`. The founder submits, and only they decide when. --- @@ -146,5 +149,7 @@ conventions at submit time. Description bullets carry **no metrics**. - Whether `e2b-dev/awesome-ai-agents` prefers the Google form over PRs in practice. - Whether awesome-browser-automation’s “Related tools” section would be a better home than AI if the maintainer reads Paragent as infrastructure rather than an AI tool. -- After #167 merges: confirm the Quick Start is clone-based (or that npm publish is real), - then flip the verdict above and let the founder submit. +- ~~After #167 merges: confirm the Quick Start is clone-based (or that npm publish is + real), then flip the verdict above.~~ **Retired** — `paragent@0.1.1` is published and + the `npx` Quick Start is verified against the published tarball. The verdict above is + flipped; the submission itself is still the founder's call.