From d8814e938ce11e4467a75f0eb334844566f25806 Mon Sep 17 00:00:00 2001 From: dotta Date: Mon, 30 Mar 2026 08:53:38 -0500 Subject: [PATCH 1/2] docs: add manual @paperclipai/ui publish steps Co-Authored-By: Paperclip --- doc/PUBLISHING.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.md index 32e4b131..a3dd02c7 100644 --- a/doc/PUBLISHING.md +++ b/doc/PUBLISHING.md @@ -76,6 +76,38 @@ The `ui` package uses [`scripts/generate-ui-package-json.mjs`](../scripts/genera After packing or publishing, `postpack` restores the development manifest automatically. +### Manual first publish for `@paperclipai/ui` + +If you need to publish only the UI package once by hand, use the real package name: + +- `@paperclipai/ui` + +Recommended flow from the repo root: + +```bash +# optional sanity check: this 404s until the first publish exists +npm view @paperclipai/ui version + +# make sure the dist payload is fresh +pnpm --filter @paperclipai/ui build + +# confirm your local npm auth before the real publish +npm whoami + +# safe preview of the exact publish payload +cd ui +pnpm publish --dry-run --no-git-checks --access public + +# real publish +pnpm publish --no-git-checks --access public +``` + +Notes: + +- Publish from `ui/`, not the repo root. +- `prepack` automatically rewrites `ui/package.json` to the lean publish manifest, and `postpack` restores the dev manifest after the command finishes. +- If `npm view @paperclipai/ui version` already returns the same version that is in [`ui/package.json`](../ui/package.json), do not republish. Bump the version or use the normal repo-wide release flow in [`scripts/release.sh`](../scripts/release.sh). + ## Version formats Paperclip uses calendar versions: From 2c75c8a1ec4e28adcbe569cdf161bd06d81c8dce Mon Sep 17 00:00:00 2001 From: dotta Date: Mon, 30 Mar 2026 12:44:26 -0500 Subject: [PATCH 2/2] docs: clarify npm prerequisites for first ui publish Co-Authored-By: Paperclip --- doc/PUBLISHING.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.md index a3dd02c7..83a6c4a7 100644 --- a/doc/PUBLISHING.md +++ b/doc/PUBLISHING.md @@ -108,6 +108,13 @@ Notes: - `prepack` automatically rewrites `ui/package.json` to the lean publish manifest, and `postpack` restores the dev manifest after the command finishes. - If `npm view @paperclipai/ui version` already returns the same version that is in [`ui/package.json`](../ui/package.json), do not republish. Bump the version or use the normal repo-wide release flow in [`scripts/release.sh`](../scripts/release.sh). +If the first real publish returns npm `E404`, check npm-side prerequisites before retrying: + +- `npm whoami` must succeed first. An expired or missing npm login will block the publish. +- For an organization-scoped package like `@paperclipai/ui`, the `paperclipai` npm organization must exist and the publisher must be a member with permission to publish to that scope. +- The initial publish must include `--access public` for a public scoped package. +- npm also requires either account 2FA for publishing or a granular token that is allowed to bypass 2FA. + ## Version formats Paperclip uses calendar versions: