Move the npm package to `framework` (publishing stays manual)

[suleimansh]

🤖 curated

From Discord: "TODO: let's move the npm package to https://npmjs.com/package/framework".

The name is already ours. framework on npm lists brillout and suleimansh as its maintainers. It was created by Mikeal Rogers in 2011 and last really published as 0.6.0 in April 2022; the registry record was modified 2026-08-11, which is the handover. So this is a rename, not an acquisition — no dispute process, no waiting on npm support.

Where we are

Published today as	@gemstack/the-framework
Latest on npm	1.5.0, published 2026-08-19 (7 versions)
package.json says	"version": "0.0.0"
Legacy versions under framework	up to 0.6.0 (2022)

Versioning is not a problem. We are already at 1.5.0, comfortably above the 2022 0.6.0, so the first publish under framework supersedes the old package cleanly. Nothing needs deprecating or unpublishing.

Nothing in the repo records what shipped. package.json is pinned at 0.0.0 while npm serves 1.5.0, so the version is decided at publish time and the repo has no memory of it. Tolerable while a human runs the command, which is what we are keeping — see the decision below.

The work

• name: @gemstack/the-framework → framework
• version: 0.0.0 → 0.7.0 (brillout, 2026-08-22 — stay in 0.x for experimental semver)
• homepage, bugs, repository: all three still point at gemstack-land/the-framework, and follow the repo to framework/the-framework
• README.md — the npm badge and both install lines (npm i -g @gemstack/the-framework, npx @gemstack/the-framework)
• Delete the 11 orphaned .changeset/*.md files (see below)

One sub-question left open: the bin is the-framework, so the command users type stays the-framework even though the package becomes framework. npx framework would then not work, which is mildly surprising. I would keep the-framework as the command — it is what the CLI, the docs and the website all say, and renaming it is a much larger change than renaming the package. Say if you would rather they match.

Decision: publishing stays manual

It used to be automatic. .github/workflows/release.yml published on every push to main via changesets, and it was deliberately deleted in a745e2e3 — "delete the release history — changesets, changelogs, migration notes, semver" — which removed 77 changesets, the changesets tooling, four CHANGELOGs totalling 2,861 lines, and reset the versions to 0.0.0.

We are leaving it deleted. The reasons, in order of weight:

• Nothing installs the package. No workflow does, and a dogfood runs node packages/the-framework/dist/bin.js from the local build. The only consumer is the README telling a human to npm i -g. A stale npm blocks no machine.
• Automation needs an NPM_TOKEN in CI — publish rights to a freshly acquired name, sitting in a repo secret, bought for a benefit nobody is waiting on.
• It would need a version policy first. 0.0.0 in the repo versus 1.5.0 on npm has to be resolved before a workflow can bump anything. A human typing the number does not need that resolved.
• This repo merges several PRs a day. "Every green main publishes" means several versions a day of a package with no installs.

This is a "not yet", not a "no". The day the package has users, automatic publishing is obviously right, and this issue is where that gets revisited.

The part that argues for doing this now: changesets are half-back

a745e2e3 removed the tooling but not the habit. Eleven .changeset/*.md files are tracked in the repo today, the newest added 2026-08-19 in #1595. Nothing consumes them: no .changeset/config.json, no @changesets/cli dependency, no release workflow, and no prompt instructing agents to write them. Agents write them from training, every PR commits more, and no process ever reads one.

So we currently carry the cost of changesets and none of the benefit. They go with this issue.

[brillout]

Let's release at 0.7.0, we might need the experimental semver versioning

[suleimansh]

🤖 curated

0.7.0 it is — and it supersedes what I wrote above. That paragraph claimed "we are already at 1.5.0, comfortably above 0.6.0"; the release line is now the framework line, not the @gemstack/the-framework one. npm's latest for framework is 0.6.0 today, so 0.7.0 publishes cleanly and takes latest. @gemstack/the-framework@1.5.0 is simply a different package that stops receiving publishes.

0.x also gets the thing you're after: while the major is 0, a minor bump is allowed to break, so no experiment costs a major.

Added to the checklist: "version": "0.0.0" → "0.7.0" in packages/the-framework/package.json, so the repo records what shipped instead of the number living only in whoever typed npm publish.

One ordering hazard. The README rewrite and the publish have to land together. The moment README.md says npm i -g framework, that command resolves — to Mikeal Rogers' 2011 package at 0.6.0, which is not us. So either the publish goes first and the rename PR merges after, or both happen in the same minute. I'd publish first; the PR can then merge whenever.

Still open: the bin stays the-framework, so npx framework would not work. Recommendation unchanged — keep the command as-is, it is what the CLI, the docs and the website all say. Option A: keep the-framework. Option B: rename the command to match the package.

[suleimansh]

🤖 automated

Published and merged. framework@0.7.0 is on npm and holds latest; PR #1639 merged as 5c25262e.

latest: 0.7.0
bin: { the-framework: dist/bin.js }
repository: github.com/framework/the-framework
published: 2026-08-22T15:56:57Z

Publish went first, merge second, so the README never pointed at Mikeal Rogers' 2011 package.

Checklist

• name: @gemstack/the-framework → framework
• version: 0.0.0 → 0.7.0
• homepage, bugs, repository → framework/the-framework
• README.md — badge and both install lines
• Delete the 11 orphaned .changeset/*.md files

Four more the checklist didn't have, where the name was load-bearing: update-check.ts:9 (the registry key the check GETs), layout.ts:71 (an install command printed to users), dashboard/README.md (pnpm --filter resolves by package name), and the website — Hero.tsx's eight install commands, ui.tsx's NPM_URL and GITHUB_URL, the press page chip.

A bug the version bump fixed. version was 0.0.0 while the CLI reads its own package.json at runtime (cli.ts:116) and asked the registry about @gemstack/the-framework, whose latest is 1.5.0. Every run of the version footer claimed an update was available. 0.7.0 against the old 0.6.0 now reports up to date.

Two npm hiccups, both transient, neither ours: a 404 on PUT (an expired token in ~/.npmrc — npm returns 404 rather than 403 on the write path), then a 409 Cannot publish over previously staged version that cleared on its own a few minutes later. No 0.7.1 needed.

Still open — the only thing left on this issue

The bin is the-framework while the package is now framework, so npx framework does not work.

Worth adding: packages/the-framework/README.md had been telling users to run framework — in both the quickstart and the CLI options block — while the bin has always been the-framework. It was documenting a command that does not exist. #1639 fixed it to match the bin, but whoever wrote it reached for framework twice without noticing, which is an argument for Option B.

• Option A — keep the command the-framework. What the CLI, FEATURES-SPEC.md, the root README and the website all say.
• Option B — rename the command to framework so package and command match.

Option B is a one-line bin change plus a docs pass. Leaving this open until you pick.