docs: remove stale DISTRIBUTION.md

[kojiwakayama]

Removes DISTRIBUTION.md (621 lines), last touched 2026-03-06 in 54f01a6.

The decision is remove, not update. It duplicates
Installation, which is the page
users actually read and the one the docs quality validator polices. A second, unpoliced copy of
installation instructions is exactly how the drift in veryfront-issue-inbox#475 happened, so
refreshing it would just reset the clock on the same failure.

What was verified wrong

Every item below was checked against the current release, not inferred.

Claim in DISTRIBUTION.md	Reality
npm package is "~50KB" and "downloads the binary during postinstall"	npm view veryfront dist.unpackedSize = 27,428,043 bytes across 7,898 files, framework inlined. Off by ~550x.
Binaries are "~254MB"; UPX section promises "254MB → 80MB"	Release v0.1.1229 assets are 0.94–1.13 GB (veryfront-macos-arm64 941 MB, veryfront-linux-arm64 1.13 GB). The whole optimization section is built on a number that is ~4x off.
"Homebrew (Future)" + a hand-written formula to create	homebrew/veryfront.rb is checked in, and cicd.yml has an update-homebrew job (line 947) that opens PRs against veryfront/homebrew-tap.
Release step: "update npm/package.json (version)"	There is no npm/ directory. Version lives in deno.json.
Release step: manual npm login && npm publish	Publishing is the RC train in cicd.yml — prepare-rc-build.ts → build:npm → publish-npm-packages.sh, under OIDC trusted publishing (id-token: write), not a static token.
"Create install.sh" with a full inlined script	scripts/install.sh already exists and has diverged: --version / --dir flags, installs to ~/.veryfront/bin (not sudo mv to /usr/local/bin), and verifies checksums.
Distribution channel list	Predates the 27 @veryfront/ext-* packages, the veryfront-proxy-* binaries, and the SBOM release assets (all.json, dependencies-by-manifest.json, per-extension JSON) entirely.

Worth noting the file was never merely stale — following its release section would have had a
maintainer editing a path that does not exist and publishing by hand outside the OIDC train.

References checked before deleting

Nothing points at this file. Searched for DISTRIBUTION.md in:

• veryfront-code — no hits outside the file itself. The only DISTRIBUTION match in the repo is
  the Apache boilerplate line in LICENSE ("TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND
  DISTRIBUTION"), unrelated.
• veryfront-docs, veryfront-studio, veryfront-api — no hits.
• README.md, CONTRIBUTING.md, AGENTS.md, CONTEXT.md — no link to it.
• .github/CODEOWNERS — not listed (it names SECURITY.md, CONTRIBUTING.md, CLA.md,
  CLA-CORPORATE.md only).
• .github/workflows/ — no reference; sync-docs.yml only watches docs/ paths.
• scripts/, tests/, src/, templates/, rfcs/, .claude/ — no reference.
• scripts/build/npm-package-metadata.ts — does not ship root markdown, so the published package is
  unaffected.

No test or lint rule asserts the file exists. The nearest analogue,
src/security/repository-hardening.test.ts, pins SECURITY.md and CODEOWNERS specifically and
never touches this file. Pre-push (fmt, lint, typecheck, full suite) is green.

Content that is NOT covered elsewhere

Per the "deleting unique information is worse than a stale file" rule, here is the audit rather than
a silent drop. Most of the file is genuinely redundant:

• User install paths → README.md already documents both curl … install.sh | sh (line 48) and
  brew install veryfront/tap/veryfront (line 50); the docs page covers every package manager.
• Maintainer release process → CONTRIBUTING.md § Release Process, plus scripts/release.ts and
  cicd.yml as the executable source of truth.
• Build commands, checksums, CI/CD YAML → superseded by the real cicd.yml, which also does SBOM
  generation the doc never knew about.

Four things have no home anywhere else. I am not claiming they should be dropped on the floor:

1. macOS quarantine troubleshooting (xattr -d com.apple.quarantine veryfront). Genuinely
   user-facing and not documented anywhere. It only bites users who download a binary from GitHub
   Releases in a browser — curl and Homebrew do not set the quarantine bit. Proposal: add it as
   a troubleshooting entry on the installation docs page, where the validator will police it.
2. macOS codesigning (codesign -s "Developer ID Application") and GPG detached signatures.
   Grepping .github/ and scripts/ for codesign / gpg returns nothing — these were never
   implemented. This is an unimplemented wish, not documentation, and the repo has since moved to
   SBOMs plus npm provenance via OIDC. Proposal: file as a supply-chain issue if still wanted,
   so it is tracked as work rather than asserted as fact.
3. UPX compression trade-off. Also never implemented, and its numbers are wrong now that binaries
   are ~1 GB. Proposal: issue, not doc — and it needs re-measuring before anyone acts on it.
4. Future channel roadmap (Chocolatey, Scoop, AUR, Snapcraft, Docker Hub). Roadmap, not
   reference. Proposal: issue-inbox items.

I did not create those issues as part of this PR — happy to, if you want them tracked.

Adjacent drift spotted, deliberately not fixed here

CONTRIBUTING.md § Release Process troubleshooting still says "Check that NPM_TOKEN secret is set",
which the OIDC trusted-publishing migration made obsolete. Left alone to keep this PR a clean
deletion; flagging it so it does not become the next DISTRIBUTION.md.

Test plan

• Full pre-push gate (fmt check, lint, typecheck, unit + integration suite): 3789 passed | 0 failed.
• First push attempt hit the known shutdown flake ("Promise resolution is still pending but the event
  loop has already resolved" after a clean 0 failed); re-ran unmodified and it passed.

Summary by CodeRabbit

• Documentation
  • Removed the distribution and installation guide.
  • Deleted instructions covering installation methods, binary releases, security, CI/CD, troubleshooting, and future distribution plans.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9503e16d-e2f7-47b3-b1d4-989fa01cecc3

📥 Commits

Reviewing files that changed from the base of the PR and between 3ffb27b and 674f0f6.

📒 Files selected for processing (1)

• DISTRIBUTION.md

💤 Files with no reviewable changes (1)

• DISTRIBUTION.md

---

📝 Walkthrough

Walkthrough

The DISTRIBUTION.md distribution and installation guide was deleted.

Changes

Cohort / File(s)	Summary
Distribution documentation removal DISTRIBUTION.md	Removes instructions for installation methods, binary builds, releases, security, CI/CD, troubleshooting, and future distribution plans.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: kwakayama

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: removing the stale DISTRIBUTION.md documentation file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/remove-stale-distribution-md

---

_{Comment @coderabbitai help to get the list of available commands.}

[kwakayama]

No actionable findings.

• DISTRIBUTION.md:1 is the sole changed path; no tracked file at head references it.
• Maintained install guidance remains at docs/getting-started/installation.md:20-143 and README.md:45-53; those are included in public-doc validation (scripts/docs/validate-public-docs.ts:23-29).
• Removal eliminates conflicting guidance, including the obsolete “Homebrew (Future)” claim at DISTRIBUTION.md:57; CI updates Homebrew releases at .github/workflows/cicd.yml:947-1005.
• Release behavior is unchanged and defined by deno.json:3 and .github/workflows/cicd.yml:481-503,768-907. Existing binary integrity handling remains untouched at scripts/postinstall.js:102-129.
• No test changes are warranted for deletion of an unreferenced Markdown document; the supplied required-check snapshot is green.

Rubric: correctness 40/40, tests 20/20, reliability/security 15/15, maintainability 15/15, scope/docs 10/10.

Review-Gate:
Reviewer: Codex
Reviewed-SHA: 674f0f6
Score: 100/100
Actionable-Findings: 0
Verdict: APPROVE