The introduction page currently serves two purposes and does neither well. The top half introduces Beacon (API listing, what signals are, how dependency tracking works). The bottom half is a changelog for the current version ("Changes from v1000.3.1", migration link).
A reader landing on the introduction page wants to understand what Beacon is, when to use it, and how to think about it. They do not want a diff against the previous release. That belongs in the migration guide, which already exists.
What the introduction should cover
- What Beacon is in one sentence
- The mental model: signals, effects, and the dependency graph
- A small working example that shows the reactive loop in action
- When Beacon is the right choice (and when it isn't)
- How to read the rest of the handbook
What should move out
- The "Changes from" section duplicates content from the migration page. Remove it from the introduction and link to migration for readers who want the version diff.
- The constraints section (line count, zero dependencies) is factual but reads as a spec sheet. Weave the relevant parts into the introduction naturally.
Per-version consideration
Every version directory has its own introduction page. The shared content (what Beacon is, mental model, example) is identical across versions. Only the "Changes from" section differs, and that section is the one being removed. After this rewrite, the introduction pages should be nearly identical across versions, varying only where the API surface genuinely changed (e.g., v1.0.0 used derived() instead of derive()).
The introduction page currently serves two purposes and does neither well. The top half introduces Beacon (API listing, what signals are, how dependency tracking works). The bottom half is a changelog for the current version ("Changes from v1000.3.1", migration link).
A reader landing on the introduction page wants to understand what Beacon is, when to use it, and how to think about it. They do not want a diff against the previous release. That belongs in the migration guide, which already exists.
What the introduction should cover
What should move out
Per-version consideration
Every version directory has its own introduction page. The shared content (what Beacon is, mental model, example) is identical across versions. Only the "Changes from" section differs, and that section is the one being removed. After this rewrite, the introduction pages should be nearly identical across versions, varying only where the API surface genuinely changed (e.g., v1.0.0 used
derived()instead ofderive()).