waypost launch runbook

State: open/active · Genre: plan

The flip that takes waypost and detect-runners public: repos, docs site, and npm. Everything below is staged and inert until a human runs it. The channel itself is documented in PUBLISHING; this file is only the ordered launch sequence. The rename pass this file used to carry is DONE — the product is waypost, installing as way — so what remains is mechanical.

Three packages ship, in this order:

command-seam -> detect-runners -> waypost

@sksizer/easy-git is NOT in that chain. detect-runners used it for two git calls — rev-parse --is-inside-work-tree and ls-files — which now run directly against the AsyncCommandRunner it already holds. Publishing a git client to public semver in order to ship a task browser was the larger cost.

State today: all three are roster entries in publish-libs.json with accurate needs, each carries a mirror-side .github/workflows/release.yml, waypost additionally carries .github/workflows/site.yml (GitHub Pages deploy of docs-site/), and the docs site keeps every brand string in packages/ts/waypost/docs-site/brand.ts. Nothing is published: no mirror repos exist, no tags are pushed, npm has nothing under any of the three scoped names.

waypost is taken on npm, unscoped. It was free in August; by September a different author’s package sits there (v0.13.0, MIT, an ADR/agent CLI) and it installs binaries wyp and waypost. @sksizer/waypost is unaffected and still free, as is sksizer/waypost on GitHub. The response was to drop our own waypost binary: this product installs one command, way. Re-check the scoped names before step 2 — free in September is not free forever.

1. The rename pass — DONE

The product was tskr, installing as tsk/tskr. It is now waypost, installing as way — see the npm collision above for why the second binary was dropped. The library kept its own name: it is a general, descriptive package and was never affected by the collision that forced the product rename.

The on-disk names moved with it, which was a deliberate product decision rather than a mechanical consequence — they are user-facing contract, and the moment before first publish was the last one where changing them was free:


project config	`waypost.config.json`
user config	`$XDG_CONFIG_HOME/waypost/config.json`
config env var	`WAYPOST_CONFIG`
cache	`$XDG_CACHE_HOME/waypost/`
trust store	`$XDG_STATE_HOME/waypost/trusted/`
server header	`x-waypost-token`

No migration was written for the trust store. Nothing was published, so the only grants that existed were on the author’s own machine; a repository trusted under the old path simply asks again. If that ever stops being true — if anyone else is running this before a rename — the answer is a one-time move on first run, not a silent reset.

2. Preconditions, once

Create the mirror repos (public, empty, no README): gh repo create sksizer/command-seam --public,
```
`gh repo create sksizer/detect-runners --public` and
`gh repo create sksizer/waypost --public`.
```
Fine-grained PAT over all three mirrors (Contents R/W and Workflows R/W) stored as the OSS_PUBLISH_TOKEN Actions secret on the monorepo — or
```
extend the existing PAT's repo list if the channel is already live.
```

Trusted publishing on npmjs.com for each package (repos sksizer/command-seam, sksizer/detect-runners and sksizer/waypost,

workflow `release.yml`) — possible only after the package exists, so the
FIRST publish uses a granular `NPM_TOKEN` secret on each mirror instead;
delete it and configure trusted publishing right after.

3. Launch, in order

Each step waits for the previous mirror workflow to go green (gh run watch --repo sksizer/command-seam, then sksizer/detect-runners, then sksizer/waypost).

Rehearse all three without pushing: gh workflow run publish-lib -f lib=command-seam, then

`-f lib=detect-runners`, then `-f lib=waypost`; confirm validation and
snapshot assembly pass.

just release-lib command-seam patch --push — zero dependencies, so this one can go out on its own.
just release-lib detect-runners patch --push — snapshot lands on the mirror, its release.yml publishes to npm.
just release-lib waypost patch --push — same; its smoke installs the just-published library from the registry.
Enable Pages on the waypost mirror: Settings → Pages → Source: GitHub Actions. The site workflow runs on the snapshot push to main; the site
```
appears at `https://sksizer.github.io/waypost/`.
```
Cloudflare mirror (later, optional): Pages project on the mirror repo, build bun install && bun run build in docs-site/, output
```
`docs-site/dist`, env `SITE_BASE=/`.
```

4. Post-flip smoke

From an empty directory: bun add -g @sksizer/waypost, then way in a real repo — the TUI boots and lists tasks. way is the ONLY binary; if
```
`waypost` also resolves, something is installing the other project's
package.
```
bunx @sksizer/detect-runners --json in a repo with a package.json — valid catalog JSON.
The site loads at the Pages URL; the install snippet on the landing page is copy-pasteable and works as written.
npm package pages show provenance once trusted publishing is on.

← Back to Notes