# Publishing pi-tldraw-cloud

Pi's catalog indexes npm packages that include the `pi-package` keyword. There is no separate submission in the documented installation flow. Catalog appearance is asynchronous and is not guaranteed immediately after npm publication.

The publication target is **`pi-tldraw-cloud@0.2.4`**, with public visibility and the `latest` tag. It includes the extension, built browser host, and `tldraw-cloud` skill. Verify that the manifest and lockfile both name the intended version before packing; publication must be confirmed against the registry.

Release checks passed 194 automated tests, typechecking, build, and package inventory. A clean offline archive installation loaded ten tools and the skill in real Pi 0.87.1 and 1.0.0. Live checks covered all ten tools, seven helpers, eight expected error cases, and five complete fresh-board native editing chains with independent literal cloud records. The final chain ran through the clean installed archive in Pi 1.0.0. A bounded reconnect preserved uncertain native work and allowed a later new edit with a fresh receipt. Sustained offline editing/export was not tested.

The suite is not fully green. One renamed-board comparison found stale `document.name` in an existing Pi view; the original failure is retained. Exporting local work, independently verifying cloud contents, and then opening a fresh view from the installed archive recovered an exact 20-record match. This does not establish a live title-propagation fix. Fresh login, an authentic read-only fixture, and the original-app reference comparison remain untested. Keep these limits in release notes rather than treating a later recovery as an erased failure.

Preserve/export uncertain local work before upgrading or closing a view. In particular, `0.2.0` could falsely report saved edits and `0.2.1` blocked execution. The README's versioned npm example targets `0.2.4`; verify that exact version after publication.

The catalog offers an unversioned install command. The `latest` tag determines which version that command installs. Catalog indexing must still be verified after publication.

## Release procedure

1. Review the README status, changelog, known failures, and untested cases, then verify the intended version in the manifest and lockfile. For live persistence claims, require an invocation receipt and a fresh independent comparison of affected literal cloud records. Screenshots, local read-back, and board timestamps alone are insufficient.
2. Confirm the public name and MIT license are appropriate for your release. The license covers this adapter, not tldraw's remote application.
3. Run `npm ci` then `npm run release:check`. If a preserved live session occupies port 5420, the test-only override `PI_TLDRAW_TEST_SANDBOX_PORT=3000 npm run release:check` uses the supported alternate port. Do not close an uncertain live view merely to free a test port.
4. Run `npm pack --pack-destination ..`. The `prepack` hook checks, tests, and builds before producing the archive. After a completed check of frozen code, `--ignore-scripts` can repack documentation-only changes; compare source and built-asset hashes with the checked archive and inspect the publication inventory. Install the actual archive cleanly and test both supported Pi loaders, tools, and skill before publication.
5. Check the publisher with `npm whoami` and reuse valid npm authorization. If sign-in is required, use `npm login --auth-type=web --registry=https://registry.npmjs.org/` and complete the normal browser and 2FA flow.
6. Publish the exact reviewed archive for the intended version with `npm publish <reviewed-archive.tgz> --access public --tag latest`.
7. Verify that exact version and the `latest` tag in the registry. Download the registry tarball and compare its digest with the reviewed archive.
8. Install the published version in a clean Pi environment. Verify all ten tools and the `tldraw-cloud` skill load, and confirm that unready or unmonitored `exec` calls fail before user code runs. Check the Pi catalog after its index updates.

The publication manifest allows only runtime source, built browser files, the workflow skill, and public documentation/license files. OAuth data, local npm configuration, tests, work directories and node_modules are excluded. There are no install or postinstall scripts.

npm authentication is required to publish. Do not announce a release until the registry verification succeeds. A GitHub repository is optional; add actual repository, homepage, and issue URLs to package.json after one exists.

## References

- https://pi.dev/packages
- https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/docs/packages.md
- https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages/