docs: rewrite the docs tree for 2.0 and add the 1.x migration guide

[dopry]

Summary

PR 10 — the finale of the 2.0 release-review series. The docs/ tree still described nuts: constructor and interceptor APIs that don't exist, /api/resolve and Atom feeds that were never ported, combined GITHUB_REPO env vars, basic auth that was never implemented, and a Heroku app.json that configured a server that could not boot. Every page is rewritten against the shipped 2.0 surface.

Changes

• NEW docs/migrating-2.0.md — every 1.x breaking change with its replacement, organized for the three audiences: server operators (env var table, webhook move), shipped update clients (what keeps working untouched, what MSIX clients must change), and module consumers (removal table incl. the GitHubBackend argument-order trap). States the 2.x guarantee: no deprecated APIs shipping.
• urls.md — full route reference plus the request vocabulary table disambiguating platform ids vs os/arch/pkg vs filetype vs format.
• module.md — real ESM constructor, options reference, beforeDownload/afterDownload events, auth-via-middleware pattern replacing the nuts interceptors.
• deploy.md + app.json — actual env vars (GITHUB_OWNER/GITHUB_REPO split, PECANS_REFRESH_SECRET, TRUST_PROXY, PECANS_BASE_PATH, PECANS_CACHE_MAX_AGE), Docker instructions. The Heroku deploy button now configures a server that boots.
• github.md — /webhook/refresh with signature verification (was /refresh + GITHUB_SECRET default secret).
• update-osx.md — fixed example: the old one built darwin_x64, an invalid platform id (underscore instead of hyphen). update-windows.md — MSIX via the format segment per feat!: update.electronjs.org-compatible format routes; remove /update ?filetype #66.
• assets.md/faq.md — token-based detection rules, arm64/msix naming guidance, 64-bit default (the "32-bit by default" claim was stale since long before the fork).
• README.md — drops the /update redirect removed in chore!: remove the 2.0-era deprecations #67 from the feature list; links the migration guide.

Verification

• npm run format:check clean over the docs; full suite still 839 green (no src changes).
• Route/env claims cross-checked against src/pecans.ts registrations and configure()/main().

🤖 Generated with Claude Code

https://claude.ai/code/session_01GtqyiALpbkcM68Bq68JcPZ

---

Generated by Claude Code

[Copilot]

Pull request overview

This PR rewrites the docs/ tree to accurately describe Pecans 2.0’s shipped HTTP surface, module API, deployment configuration, and GitHub webhook behavior, and adds a comprehensive 1.x → 2.x migration guide.

Changes:

• Adds a new 1.x → 2.x migration guide documenting all breaking changes and replacements.
• Replaces/updates documentation pages for routes, update clients (macOS/Windows), module usage, API, assets, GitHub webhook, deployment, and FAQs to match the 2.0 implementation.
• Updates README.md and app.json to align top-level guidance and Heroku deployment configuration with the 2.0 surface.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Updates route list and links to the new 1.x → 2.x migration guide.
docs/urls.md	Rewrites the route reference and request vocabulary for 2.0.
docs/update-windows.md	Updates Windows auto-updater guidance including MSIX format-segment routes.
docs/update-osx.md	Updates macOS auto-updater guidance and correct platform id examples.
docs/SUMMARY.md	Restructures the docs navigation and adds the migration guide entry.
docs/README.md	Refreshes docs index links and naming (macOS/module/API).
docs/module.md	Updates module usage for ESM, Express router composition, backend options, and download events.
docs/migrating-2.0.md	New migration guide covering runtime, env vars, route removals/behavior changes, and module API removals.
docs/github.md	Updates GitHub webhook documentation to /webhook/refresh with signature verification semantics.
docs/faq.md	Updates FAQ answers to match 2.0 behavior (auth, backends, feeds removal, naming, etc.).
docs/deploy.md	Updates deployment instructions and documents current env vars and Docker/Heroku guidance.
docs/assets.md	Updates asset naming/detection rules and download priority to match current resolution behavior.
docs/api.md	Updates API reference to 2.0 endpoints and response shapes.
app.json	Updates Heroku env var declarations to match current configuration surface.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

docs/urls.md:21

• The sentence tying aliases to the ${process.platform}-${process.arch} matrix is slightly inaccurate because darwin-universal is not a possible process.arch value (it’s a build artifact/alias, not a runtime arch). Rewording avoids implying a client can compute darwin-universal from ${process.platform}-${process.arch}.

Platform aliases cover the `${process.platform}-${process.arch}` matrix a
modern Electron app can produce: `darwin-x64`, `darwin-arm64`,
`darwin-universal`, `win32-x64`, `win32-ia32`, `win32-arm64`, `linux-x64`,
`linux-arm64`, plus legacy names (`darwin`, `mac`, `win32`, `osx-x64`, ...).