chore: initialize modernization analysis

.gitignore

@@ -0,0 +1,30 @@
+# World of Warcraft local state
+WTF/
+**/WTF/
+SavedVariables/
+**/SavedVariables/
+*.lua.bak
+
+# Packaging and build output
+dist/
+build/
+release/
+packages/
+*.zip
+
+# Generated Lua artifacts and logs
+*.luac
+*.log
+logs/
+
+# OS metadata
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# IDE metadata
+.idea/
+.vscode/
+*.code-workspace
+*.swp
+*.swo

ACKNOWLEDGEMENT.md

@@ -0,0 +1,22 @@
+# Acknowledgement and provenance
+
+Bejeweled was created by PopCap Games, Inc. The preserved legacy implementation and bundled audiovisual assets originate from PopCap's World of Warcraft addon. Historical notice: “Copyright © 2000, 2008 PopCap Games, Inc. All rights reserved.” PopCap, Bejeweled, the PopCap logo, World of Warcraft, and related marks belong to their respective owners.
+
+This community modernization is independent, unofficial, and not affiliated with, endorsed by, sponsored by, or approved by PopCap Games, Electronic Arts, Blizzard Entertainment, or their affiliates.
+
+## Legacy snapshot
+
+The analysis reference is the Mainline implementation from Git commit `6faec1c` of the source repository. `Legacy/Bejeweled_Mainline.lua` and `Legacy/Bejeweled_Mainline.toc` preserve that snapshot byte-for-byte at the Git blob level. `Bejeweled/images/` and `Bejeweled/sounds/`, including `Bejeweled/images/Contb___.ttf`, are likewise preserved from that commit.
+
+The historical distribution included notices for PopCap, Lua 5.1.3, and LuaSrcDiet. It identified Lua as “Copyright © 1994–2008 Lua.org, PUC-Rio” and LuaSrcDiet as “Copyright © 2005–2008 Kein-Hong Man.” Both notices accompanied MIT license terms in that distribution. This file carries forward that attribution; it does not assert ownership of the preserved material or expand the rights originally granted by its owners.
+
+## License boundary
+
+The repository's `LICENSE` applies only to newly authored modernization code and documentation contributed under that license. It does **not** grant rights to:
+
+- anything under `Legacy/`;
+- anything under `Bejeweled/images/`;
+- anything under `Bejeweled/sounds/`; or
+- the bundled `Bejeweled/images/Contb___.ttf` font.
+
+Those exclusions remain subject to their original ownership and terms. No license to any trademark is granted.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bejeweled Modernization Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Legacy/Bejeweled_Mainline.toc

@@ -0,0 +1,12 @@
+## Interface: 120001, 120005, 120007
+## Title: Bejeweled
+## Version: 12.0.7
+## Notes: The popular game Bejeweled, for World of Warcraft!
+## Author: PopCap Games, Inc.
+## X-ArcadePanel: getglobal("BejeweledWindow"):Show();
+## X-ArcadePanelGraphic: interface\addons\bejeweled\images\bejeweled
+## X-ArcadePanelDescription: The popular game Bejeweled, now for World of Warcraft!\n\n(c) 2000, 2008 PopCap Games Inc. All right reserved.
+## SavedVariables: BejeweledData
+## SavedVariablesPerCharacter: BejeweledProfile
+
+Bejeweled_Mainline.lua

README.md

@@ -0,0 +1,31 @@
+# Bejeweled modernization
+
+This branch is an analysis-only bootstrap for a Mainline-first modernization of the legacy World of Warcraft Bejeweled addon. It is intentionally **not installable or playable**: there is no runtime TOC and no modernized Lua module yet.
+
+## Status and phase gate
+
+The preserved 8,401-line Mainline source must be analyzed sequentially, in evidence-backed batches, before runtime work begins. All behavior-critical shortened symbols must be resolved and all batches must be complete before any public Lua API, runtime module, modern TOC, packaging, or release work is added.
+
+Batch 01 (lines 1–500) is documented. The remaining batches are scheduled but not analyzed.
+
+## Goal
+
+The eventual addon will target current Retail/Mainline World of Warcraft while preserving gameplay behavior and the `BejeweledData` and `BejeweledProfile` SavedVariables wire formats until complete analysis supports an explicit migration.
+
+## Repository layout
+
+- `Legacy/` — immutable Mainline Lua and TOC reference from source commit `6faec1c`.
+- `Bejeweled/images/` — immutable legacy images and bundled font.
+- `Bejeweled/sounds/` — immutable legacy sounds.
+- `docs/analysis/` — sequential batch reports, identifier ledger, and exact coverage schedule.
+- `docs/architecture.md` — future module ownership and data flow; not an implementation.
+- `docs/api-baseline.md` — verified Retail API constraints for future implementation.
+- `plan.md` — the bootstrap specification executed by the root commit.
+
+## Contributing
+
+Analysis contributions must proceed in schedule order and cite exact legacy line numbers. Record every shortened identifier by declaration and lexical scope, distinguish evidence from inference, retain unresolved names when proof is incomplete, and update the shared ledger with each batch. Do not edit preserved legacy code or assets.
+
+Runtime contributions are premature until all 8,401 lines have been covered exactly once and behavior-critical symbols are resolved. Future Lua must remain Lua 5.1 compatible and must use current, verified Mainline APIs.
+
+See `ACKNOWLEDGEMENT.md` for attribution and the boundary between preserved legacy material and newly authored MIT-licensed work.

docs/analysis/batch-schedule.md

@@ -0,0 +1,25 @@
+# Exact analysis schedule
+
+The immutable analysis source is `Legacy/Bejeweled_Mainline.lua` from commit `6faec1c`, containing exactly 8,401 physical lines. The closed intervals below are consecutive and partition `[1, 8401]`: every line appears once, with no gaps or overlaps.
+
+| Batch | Inclusive lines | Count | Report | Status |
+| ---: | ---: | ---: | --- | --- |
+| 01 | 0001–0500 | 500 | `lines-0001-0500.md` | complete |
+| 02 | 0501–1000 | 500 | `lines-0501-1000.md` | pending |
+| 03 | 1001–1500 | 500 | `lines-1001-1500.md` | pending |
+| 04 | 1501–2000 | 500 | `lines-1501-2000.md` | pending |
+| 05 | 2001–2500 | 500 | `lines-2001-2500.md` | pending |
+| 06 | 2501–3000 | 500 | `lines-2501-3000.md` | pending |
+| 07 | 3001–3500 | 500 | `lines-3001-3500.md` | pending |
+| 08 | 3501–4000 | 500 | `lines-3501-4000.md` | pending |
+| 09 | 4001–4500 | 500 | `lines-4001-4500.md` | pending |
+| 10 | 4501–5000 | 500 | `lines-4501-5000.md` | pending |
+| 11 | 5001–5500 | 500 | `lines-5001-5500.md` | pending |
+| 12 | 5501–6000 | 500 | `lines-5501-6000.md` | pending |
+| 13 | 6001–6500 | 500 | `lines-6001-6500.md` | pending |
+| 14 | 6501–7000 | 500 | `lines-6501-7000.md` | pending |
+| 15 | 7001–7500 | 500 | `lines-7001-7500.md` | pending |
+| 16 | 7501–8000 | 500 | `lines-7501-8000.md` | pending |
+| 17 | 8001–8401 | 401 | `lines-8001-8401.md` | pending |
+
+Count check: `16 × 500 + 401 = 8,401`.