tunnel: package hygiene — split build/dist, untrack artifacts, harden publish

.changeset/tunnel-package-hygiene.md

@@ -0,0 +1,17 @@
+---
+"subtext": minor
+---
+
+tunnel: package hygiene — split build/dist, untrack artifacts, harden publish.
+
+Cleans up the publish flow so the tarball is always self-contained and local
+builds can't get into a half-built state.
+
+- `tunnel/build/` and `tunnel/dist/` are now gitignored; reproducible from
+  sources via `npm run build` / `npm run bundle`.
+- `bin`/`files` point at `dist/`; `prepack` runs `bundle` so `npm publish` and
+  `npm pack` are always self-contained.
+- `npm test` and `npm run build` are self-bootstrapping (`clean && tsc`).
+- Adds `npm run verify` (`npm pack --dry-run`) for quick "what would ship?" checks.
+- `main.ts` walks up to find `package.json` so it works from both the tsc
+  output (`build/src/main.js`) and the rollup bundle (`dist/index.js`).

.gitignore

@@ -7,3 +7,8 @@ node_modules/
 # Local design docs, plans, and skill-eval writeups. Authored alongside
 # implementation work but not part of the shipped plugin surface.
 docs/
+
+# Tunnel package build artifacts. tsc emits to build/, rollup emits to dist/.
+# Both are reproducible from sources; npm publish regenerates them via prepack.
+tunnel/build/
+tunnel/dist/

CLAUDE.md

@@ -18,3 +18,16 @@ Version bumps are automated via [Changesets](https://github.com/changesets/chang
 For any user-facing PR, run `npm run changeset`, pick a bump type, and commit the generated `.changeset/*.md` file. On merge to `main`, the workflow opens a "Version Packages" PR that bumps `package.json` and syncs the version into all harness manifests (`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, and `marketplace.json`) via `scripts/sync-manifest-versions.mjs`. Merging that PR creates the git tag and GitHub release.
 
 See [`.changeset/README.md`](.changeset/README.md) for the full workflow. Pure-infra / docs PRs can skip the changeset.
+
+# Tunnel Development
+
+`tunnel/build/` and `tunnel/dist/` are gitignored build artifacts — never commit them.
+
+| Script | What it does |
+|--------|--------------|
+| `npm run build` | `clean` then `tsc` → emits JS to `build/` (used by tests and local dev) |
+| `npm run bundle` | `build` then `rollup` → emits the single-file CLI to `dist/` (what npm ships) |
+| `npm test` | `build` then `node --test` (self-bootstrapping; no stale build surprises) |
+| `npm run verify` | `npm pack --dry-run` — shows exactly what `npm publish` would ship |
+
+`prepack` runs `bundle` automatically, so `npm publish` and `npm pack` are always self-contained even if you forget to run `bundle` first.