Parsing guide "Durotar (+250 rep)": code [USE19851] not recognised
in line "6{G82.8,79.1 Ashenvale}Use ...

Background — what v2.0.0 actually did vs. what it claimed

• The emitted tag (USE) was never a GuideLime tag. The fix was a one-character swap (USE → UI).
• The 30 bundled guides that contained at least one use-at-object step (~112 lines total, top-affected: Darnassus 15, Exodar 14, Silvermoon 11, Thunder Bluff 10) failed to load on v2.0.0 because of these lines. v2.0.0.md is left as-is — it represents what the v2.0.0 build was intended to do; v2.0.1 is what actually works.

What changed in v2.0.1

Emitter: [USE<id>] → [UI<id>]

-[G 82.8,79.1 Ashenvale]Use [USE19851] at the Grom's Monument for [QC8150]
+[G 82.8,79.1 Ashenvale]Use [UI19851] at the Grom's Monument for [QC8150]

Living docs updated to match the actual emission

• docs/caveats.md (§ use-at-object linker example + the pre-commit grep recipe)
• docs/pipeline.md (the _tag_qc swap callout)
• docs/experiments.md (M10 milestone description)
• guides_generator/cmangos/fetch.py (slim-data docstring example)

Compatibility

• Lua bytes change only on use-at-object lines (~112 across the 30-addon corpus). Every other line is byte-identical to v2.0.0.
• Routing / tour shape / rep-per-distance ratio identical to v2.0.0 (rep/dist 14.94, distance 42959y, byte-identical determinism).
• No .toc change — DefaultState: disabled carries forward.
• No CLI surface change. No cache schema change. Existing cache/<expansion>/cmangos_*.json sidecars stay valid.

v2.0.0

Headline

                v1.7.6   v2.0.0   Δ
Global Rep/Dist  17.08    14.94   −2.14   honest-distance correction
Total Distance   37582y   42959y  +5377y
X-Jumps            417      461   +44
Determinism      random   byte-identical across runs

1. Multi-source quest walks (Iverron's Antidote, Battle of Hillsbrad, the Manaforge shutdowns, …): v1 emitted one objective stop at the densest spawn and dropped the rest, hiding ~32000y of walking globally. v2 emits one stop per game objective.
2. Use-item-at-object walks (Crown-of-the-Earth Phial Moonwell chain, Altar steps, Spell-Focus quests): v1 emitted neither the Moonwell nor the item link, the player had to walk there blindly. v2 surfaces the GameObject coord and a clickable [USE<item>] tag.

What changed for the player

Determinism

Multi-source quest honesty

Use-item-at-object honesty

[G 63.4,58.1 Teldrassil]Use [USE5619] at the Starbreeze Moonwell for [QC929]

Cluster headers removed

Cross-chain combine refusal

Quest requirements highlighted

Pick up [QA4161] (|cffff8800NEEDS Cooking 1|r)

What changed for developers

One ranking metric, end-to-end

Hard rules gate the optimisation

Soft scores actively drive refinement

• weighted soft scores) directly, not just the multistart selection.

Three external data sources, one job each

Documentation reorganised

Compatibility

• .toc files unchanged from v1.7.6 (DefaultState: disabled, faction-disabled-by-default).
• Lua tag set extended with [USE<itemId>] — supported by current GuideLime versions.
• No CLI surface change. python3 create.py [--all | --faction X] works as before.
• Cache layout extended with cmangos_*.json sidecars + the tbcmangos.sql raw DB. Wiping cache/<expansion>/ re-fetches everything; the cmangos download takes ~30-60 s on first run.
• dist/<expansion>/_quality_report.md schema unchanged (one extra diagnostic line for the soft scores).

v1.7.6

What changed

DefaultState: Enabled → DefaultState: disabled

 ## Dependencies: Guidelime
-## DefaultState: Enabled
+## DefaultState: disabled
 ## LoadOnDemand: 0

• Before v1.7.6: a new install enabled all 30 factions, the GuideLime guide list filled up immediately, and users had to hunt-and-disable the 25+ factions they did not want.
• From v1.7.6 onwards: a new install enables zero faction guides by default. The user ticks the boxes for the factions they intend to farm in WoW's AddOns screen.

CurseForge description rewritten around the new default

Compatibility

• Lua bytes are byte-identical to v1.7.5.
• Existing users keep their saved enable / disable preferences from WTF/. The TOC default only applies when WoW first encounters an addon folder it has never seen before.
• No CLI surface change.

v1.7.5

What changed

TOC headers gain four explicit directives

 ## Interface: 20504
 ## Title: Guidelime ThPi - <Faction> Rep Farm
 ## Notes: ...
 ## Author: ThPi
 ## Version: <version>
 ## Dependencies: Guidelime
+## DefaultState: Enabled
+## LoadOnDemand: 0
 ## X-Category: Quests
+## X-License: GPL-3.0-or-later

• X-License: GPL-3.0-or-later — declarative license metadata so CurseForge / WoWInterface / Wago tooling and addon managers can surface the license without parsing the bundled LICENSE file.
• DefaultState: Enabled and LoadOnDemand: 0 — explicit defaults, matching the convention AtlasLootClassic uses. No behaviour change; these were already the implicit defaults.

One-line CurseForge summary file

• addon.build_curseforge_summary(expansion) — returns the summary string.
• addon.write_curseforge_summary(expansion) — writes it to disk.

addon package surface

+ build_curseforge_summary
+ write_curseforge_summary

Compatibility

• Lua bytes are byte-identical to v1.7.4. Only the per-addon .toc files and dist/<expansion>/ artefacts change.
• Existing user enable / disable preferences are unaffected: DefaultState: Enabled is the implicit default WoW already used, and saved preferences in WTF/ override TOC defaults anyway.
• No CLI surface change.

v1.7.4

What changed

Bundle zip is now folders-only

Install instructions move to the project page

• "Recommended: CurseForge desktop app" — the app handles multi-folder bundles natively.
• "Manual install" — drill into the wrapper folder your unzipper creates, copy the inner addon folders into Interface/AddOns/, not the wrapper.
• A visual tree comparison of correct vs wrong placement.
• "After install" — enable only the factions you intend to farm.

addon package surface

- build_bundle_readme

Compatibility

• No routing or addon-content change. Lua bytes, .toc content, the per-addon README.md, CHANGELOG.md and LICENSE are byte-identical to v1.7.3.
• The bundle zip on disk is smaller by exactly the bundle README; the per-faction addon folders inside are unchanged.
• Public API: build_bundle_readme is removed; existing code that imported it should switch to build_curseforge_description.

v1.7.3

What changed

Single umbrella bundle on --all

New addon/curseforge.py module

• build_bundle_readme(expansion, version) — the README.md that lands at the zip root. Explains what the bundle is, walks through install via the CurseForge app vs manual unzipping (with a visual tree showing the wrapper-folder gotcha), and lists every bundled faction with its in-game folder name grouped by faction group.
• build_curseforge_description(expansion, version) / write_curseforge_description — paste-ready markdown for the CurseForge project page itself, dropped next to the bundle zip as dist/<expansion>/CURSEFORGE_DESCRIPTION.md.

Per-addon README gains a bundle notice

Pipeline integration

addon package surface

- zip_addon
+ zip_addon_bundle
+ bundle_zip_path
+ build_bundle_readme
+ build_curseforge_description
+ write_curseforge_description

Repo readme

Compatibility

• Output: addon contents (.toc, .lua, README.md, CHANGELOG.md, LICENSE) are byte-identical to v1.7.2. Only the packaging changes — one bundle zip instead of 30, plus the new bundle README and CurseForge description files in dist/.
• CLI: no surface change. --all and --faction keep their semantics. Only --all produces the bundle archive; --faction still writes only the addon directory.
• Public API: zip_addon is removed. Callers that want to bundle programmatically should use zip_addon_bundle(addon_paths, expansion, version, bundle_readme=...) from guides_generator.addon.

v1.7.2

What changed

Wider anchor candidate pool

Effect on the test corpus

Runtime cost

Tests that did not make it (documented in _experiments_history.md)

• Stop-level Held-Karp cap raised 30 → 35: +0.01 rep/dist globally, not worth the runtime cost or the additional memory footprint at the cap.
• JUMP_PENALTY lowered 45 → 30: looks like +7 % in the report but is a metric artefact — distance shrinks because the solver takes more cross-zone shortcuts (zero-cost in the report), but cross-zone jumps rise +18 % and the real-world cost (dist + 45 × jumps) is actually 1.3 % worse than baseline. Dropped.

Files changed

• guides_generator/routing/start.py — LEVEL_TOLERANCE = 2, MAX_START_CANDIDATES = 6, candidate filter widened.
• _experiments_history.md — adoption note + null-result entries for the HK-cap-35 and JUMP_PENALTY tuning experiments.
• readme.md — MAX_START_CANDIDATES constant table updated.

v1.7.1

What changed

Multi-anchor start

Effect on the test corpus

Quest-sharing experiment (null result, no production change)

Runtime cost

Files changed

• guides_generator/routing/start.py — pick_start_candidates, MAX_START_CANDIDATES = 4.
• guides_generator/output/sub_guide.py — _pick_best_start helper, natural-tier dispatch.
• _experiments_history.md — multi-anchor results and quest-sharing null result.
• readme.md — routing description plus the new MAX_START_CANDIDATES constant.

v1.7.0

What changed

Stop-level Held-Karp DP

• Sparse dict[(mask, last)] over reachable states instead of a dense 2^N · N table. Most masks are unreachable under precedence, so the actual state count is typically a few hundred to a few thousand even at the cap.
• Forward expansion: the DP builds the reachable set on the fly, rather than allocating up front and visiting infeasible states.

compute_tour_stats start-position fix

Sub-guide impact

• N ≤ 12 stops: usually unchanged (the entry-level Held-Karp already fired and found the same answer, modulo cluster atomicity).
• 13 ≤ N ≤ 30: now provably optimal. Empirically a handful of buckets tighten by 0.3–1.0 % rep/dist; most were already at the optimum the heuristic chain found.
• N > 30: unchanged.

Files changed

• guides_generator/routing/held_karp.py — new pass, shared helpers.
• guides_generator/routing/tour.py — wire stop-level HK into refine_tour.
• guides_generator/output/sub_guide.py — pass start_pos to compute_tour_stats.
• _experiments_history.md — post-v1.6.x section explaining the number drop and the new pass.
• readme.md — routing description and constants table updated.

v1.6.2

What changed

Auto-zip on --all

Module additions

• guides_generator/addon/zipper.py — new zip_addon(addon_dir, expansion) function. Pure stdlib (zipfile); no extra deps.
• guides_generator.constants.DIST_DIR — ./dist, configurable alongside ADDONS_DIR and CACHE_DIR.

Compatibility

• No routing or output change. Lua bytes, .toc content, README, CHANGELOG and LICENSE are byte-identical to v1.6.1.
• --faction runs are unchanged (no zip step). The zipper is wired into run_all only.
• Generated zip directory is gitignored together with addons/ and cache/ — they all regenerate from source on every run.

v1.6.1

What changed

License: GPL-3.0-or-later

• New LICENSE file at the repo root carries the full GPL-3.0 text.
• The license is GPL-3.0-or-later so the generated sub-addons stay license-compatible with GuideLime (the parent addon, GPL-2.0-or-later).
• readme.md gains a License section explaining the choice.

LICENSE bundled in every addon

CurseForge project descriptions split out

Readme markdown fix

Compatibility

• No routing change, no Lua-output change. Every faction's Global Rep/Dist, distance, x-jumps and absorption rate are byte-identical to v1.6.0.
• Each addon's .toc ## Version field bumps to 1.6.1 and a LICENSE file appears next to the existing files. Players who overwrite their addon directory get the new license metadata automatically.
• No CLI surface change.

v1.6.0

What changed

Verb-led step bodies

No more chain bookkeeping

Module cleanup

• guides_generator/chains.py and guides_generator/output/chain_index.py are deleted. find_chains, topo_sort, and disambiguate_duplicate_names were only used to render the now-removed chain index and per-step markers.
• output/sub_guide.py no longer threads display_names and quest_pos into the emitter — both arguments are gone from GuideEmitter.emit_tour and the per-step builders.

Quality report intro trimmed

Quality report

Compatibility

v1.5.1

What changed

• routing.multistart spawns a multiprocessing.Pool with one worker per logical CPU (os.cpu_count()). The K candidate builds per sub-guide are now distributed via Pool.starmap instead of running serially. The pool is created lazily on first use and reused across the whole bulk run, so per-task pickling cost amortises over many sub-guides.
• K bumped from 64 to 96. Multiprocessing introduces a tiny tie-breaking variance (workers can return same-cost candidates in a different order than the serial sweep would have produced), which on its own would cost about 0.01 rep/dist. Running K=96 instead of K=64 absorbs that variance — and lands the headline metric slightly above the serial v1.5.0 ceiling. Extra candidates run in parallel for free on a multi-core host, so wallclock barely moves.

Quality report

What was tried and dropped

• Adaptive K (smaller K for tiny sub-guides): tested with tiers K=8/32/64/96 keyed on stop count. Reduced runtime modestly but cost 0.03 rep/dist because the smaller-K sub-guides occasionally missed the optimum the K=64 pipeline reliably found. Flat K=96 beats it on both quality and consistency.

Determinism

Compatibility

v1.5.0

What landed

Always-on multistart routing

1. Greedy build with cluster discovery + on-the-way absorption.
2. Multistart — K=64 randomized rebuilds, cost-aligned acceptance (distance + JUMP_PENALTY × jumps). Diversification on three axes: random anchor, stochastic top-3 next-stop pick, cluster-radius jitter on half the iterations. ILS finisher with mixed segment-reverse + Lin-Kernighan-style double-bridge perturbations.
3. Deep refinement on the winner — alternating 2-opt + or-opt to convergence, 3-opt for tours with ≤50 entries, defrag pass, Held-Karp DP for tours with ≤12 entries, stop-level 2-opt finisher, stop-level or-opt finisher.

Module additions

• multistart.py — orchestrator + stochastic-greedy build + ILS perturbation kernels.
• held_karp.py — exact DP for tours ≤12 entries.
• three_opt.py — three-cut reconnection sweep.
• stop_2opt.py — stop-level 2-opt with cost-aligned acceptance.
• stop_or_opt.py — stop-level or-opt with cost-aligned acceptance.

Helper

Quality report

What was tried and dropped

• Random-insertion construction regresses (-1.6% distance) — fragments same-coord stops the greedy build clusters for free.
• Larger or-opt segments (k=5,6) regress slightly — more candidates divert the alternating search into worse local optima.
• Plain simulated annealing on top of converged 2-opt: zero change on its own.
• Cluster-defrag as a quality signal: cosmetic only under rep/dist (still kept in the chain because tighter Lua emission is nice; not because it improves the metric).

Compatibility

v1.4.0

Why

What changed

• output.score removed. No more compute_efficiency_score.
• Sub-guide title drops (Eff. <score>, ...); now just (+<rep> rep). The description block also no longer prints a score line.
• Per-addon QUALITY_REPORT.md snapshot leads with Rep/Dist, not ø Score. Sub-guide table is sorted by Rep/Dist descending. Score column is gone. Distance, x-jumps, absorption rate stay as diagnostics.
• Global _quality_report.md snapshot leads with Global Rep/Dist. Faction comparison is sorted by N-Rep/Dist descending. Top/Bottom-20 sub-guide lists rank by rep/dist. Global ø Score is gone.
• Documentation (readme.md, caveats.md) updated. Section 14's historical "score deltas" table is annotated to clarify the numbers predate this metric switch.

Quality report

Migration notes for branches

v1.3.2

What changed

Per-addon QUALITY_REPORT.md

• python3 create.py --faction sporeggar → updates only that addon's report.
• python3 create.py --all → writes one per addon (30 files for TBC).

Slim global _quality_report.md

• Snapshot — the headline KPIs (ø Score, Efficiency, Distance, X-Jumps, Absorption, Lost Quests, Sub-Guides Total).
• Faction Comparison — one row per faction with the columns that move with code changes.
• Top 20 / Bottom 20 Sub-Guides by Score — global optimisation candidate list across all factions.

report package API

• report.write_addon_report(stats, addon_dir, fname, fid, version, expansion) — writes one <addon_dir>/QUALITY_REPORT.md and returns its path.
• report.write_global_report(results, addons_root, version, expansion) — writes the slim _quality_report.md at the repo root. No-ops silently if results is empty (so single-faction runs that wire it in for symmetry would not crash).

Quality report

v1.3.1

What changed

1. Natural-tier phase — every (zone, natural) bucket, sorted by the zone's level tier (city hubs and unmapped zones fall in by their average quest level).
2. Cleanup phase — every (zone, cleanup) bucket, sorted by average quest level.

[N 10-20 Darkshore]  ...  [N 20-30 Hillsbrad]  ...  [N 9-55 Darnassus]
[N 30-40 Desolace]  [N 31-31 Darkshore (Cleanup)]  [N 35-45 Feralas]
[N 40-50 The Hinterlands]  ...  [N 47-47 Thousand Needles (Cleanup)]
[N 48-55 Felwood]  ...

[N 10-20 Darkshore]  ...  [N 20-30 Hillsbrad]  ...  [N 30-40 Desolace]
[N 35-45 Feralas]  [N 40-50 The Hinterlands]  ...  [N 48-55 Felwood]
[N 50-58 Burning Steppes]  ...  [N 62-65 Terokkar Forest]
[N 31-31 Darkshore (Cleanup)]  [N 47-47 Thousand Needles (Cleanup)]

Quality report

What was tried and rejected

Unlocking-power tiebreaker

Multi-restart routing

v1.3.0

Or-opt refinement (new)

Alternating 2-opt + or-opt with early exit

O(n²) → O(n) spawn clustering

What was tried and rejected

• Followup-aware absorption (idea: bigger detour budget if the candidate's quest has a follow-up stop near the travel target): the absorption corridor is too narrow under the current cluster radius for this signal to help; aggressive bonus values regressed Score by 1.0 because the algorithm absorbed long-detour stops and clusters fragmented.
• JUMP_PENALTY tuning (sweep 30/45/60/75/90): JP=30 won by +0.1 Score and -3.7% distance, but added +10% X-Jumps — semantically more expensive for the player than the score reflects.
• DETOUR_THRESHOLD tuning (4/6/8/10/12): identical KPIs across the whole range. Cluster-discovery already absorbs anything within cluster_radius; the absorption corridor is too narrow for tuning this knob to matter.

Files

• guides_generator/routing/or_opt.py — new
• guides_generator/routing/tour.py — alternating refinement loop with convergence-based early exit
• guides_generator/coords/geometry.py — grid-based cluster_spawns

v1.2.0

How it works

• Initial cluster discovery centres on the spawn instead of the first feasible stop in arbitrary input order.
• 2-opt cost function treats the spawn as the start of the tour, so reverse-segment moves that bring early stops closer to the spawn are preferred.

Effect on the quality report

• The Consortium: 961 → 847 dist (-12%), score 82 → 84
• Undercity: 3051 → 2841 dist (-7%), score 64 → 65
• Ironforge: dist -32, score 58 → 59

Files

• routing/start.py — new module, contains pick_start_position.
• routing/tour.py — route_subguide no longer falls back to a default anchor; the caller decides explicitly.
• output/sub_guide.py — passes start_pos only when bucket == 'natural'.
• routing/__init__.py — re-exports pick_start_position.

v1.1.0

Per-addon README

• New ## Support the project block sits directly under the intro (was buried near the bottom under ## A note on the guide content). Wording matches the project-level readme.md exactly.
• New ## Addon info block right after Support — collects faction, game version, addon version, author, and repository link in one bullet list (previously these lines floated unstructured between intro and Requirements).
• The BUY_ME_A_COFFEE_URL constant is gone from constants/paths.py; the URL is hardcoded in addon/readme.py (only one consumer, no reason to abstract). The placeholder/"link coming soon" fallback is removed too.

Module reorganisation

Why split

• output.py and cli.py had each grown well past 700 lines and mixed several unrelated concerns (text sanitisation + emitter state
  • sub-guide assembly + scoring; CLI parsing + pipeline orchestration
  • Markdown report rendering).
• The quality report alone was 350+ lines living inside cli.py. It is now its own report/ package with one module per concern (aggregate pathing, render the seven Markdown sections, write the file).
• Routing was a single 436-line file mixing data types, distance helper, feasibility check, cluster discovery, on-the-way absorption, 2-opt, and tour-stats aggregation. Each is a separate module now.

Verification

Repository hygiene

• _quality_report.md is now tracked instead of ignored, so changes to routing or scoring show up in PR diffs.
• readme.md "Project layout" / "Configuration" sections rewritten for the new package structure (paths into the relevant subpackage, routing constants annotated with the file they live in).

v1.0.0

Generated guide structure

• One sub-guide per zone, split into a natural tier (level fits the zone) and a cleanup tier (higher-level returns).
• A chain index at the top of every sub-guide lists the quest chains contained in it.
• A complex section at the end of a zone's sub-guide collects cross-zone chains whose entry quest is picked up here.
• Self-contained sub-trees of mixed-zone components are kept in the normal section: only quests whose entire ancestor chain stays in one zone are emitted there; the rest move to complex.
• Solo cross-zone quests (different pickup vs. turnin zone, no chain partners) move to the complex section so optional cross-zone work is grouped at the end.

Routing

1. Cluster discovery: collect every feasible stop within the per-zone cluster radius of the current position; each picked stop becomes the new centre and the search repeats.
2. Travel: pick the nearest still-feasible stop further away.
3. On-the-way absorption: while travelling, absorb stops whose detour stays under 6 map units. Stops already inside the destination's cluster are deferred to the next cluster pass.
4. 2-opt post-pass: reverse-segment swaps that reduce total cost while preserving precedence. Cost is jump-aware: intra_zone_distance + JUMP_PENALTY * cross_zone_jumps (JUMP_PENALTY = 45 map units — one zone change costs as much as 45 walking units).

Cluster radius per zone

Chain-bucket coalescing

Output format

[OC]Quest chains in this zone:
[OC]  Chain 1: A -> B -> C
[OC]  Chain 2: X -> Y

*Honoring a Hero*: [QA8149]
*Balance of Nature*: [QC456][TAR2031][TAR1984]

[OC]At (34.8, 9.3) in Darnassus: 2x pickup, 1x turnin
*Un'Goro Soil*: [QA3764] *Chain 3 1/4*
*The New Frontier*: [QA6761]
*The New Frontier*: [QT6761] (+10 rep)

• Sage-style tags: tag bodies carry only the ID ([QA8149] / [QT8149] / [QC8149]); the quest name is the italic prefix in front of the tag, resolved by GuideLime from its own DB at runtime.
• Combined-range marker *Chain 3 2->3/4* when a turnin and the next pickup of the same chain merge at one NPC.
• Cluster header is only emitted when the cluster has more than one stop (otherwise it would just repeat the location).
• [A <race/class>] runtime race/class filtering for faction-specific quests.
• [TAR<id>] click-to-target macros for objective NPCs.
• (Pt. N) disambiguation for chains with duplicate-named members.
• Annotations: (repeatable), (needs Honored), (needs Cooking 50), etc., emitted next to the QA step.

Output sanitiser

• _safe_text replaces multibyte-UTF-8 punctuation with ASCII equivalents (× -> x, → -> ->, — -> --, smart quotes, NBSP) and drops anything else outside ASCII except whitelisted German umlauts (raw rendering bug in some GuideLime builds).
• _safe_tag_content additionally maps [ to ( and ] to ), so test/dev NPCs named [PH] Foo cannot close a TAR tag early.

Data sources

• Quest, NPC, object, and item databases pulled from Questie (auto-download + cache).
• Coverage: ~97% pickup, ~99% turnin, ~40% objective coordinates.
• Item-drop bridges: bridge quests auto-started by an item drop resolve via the source NPC; if that NPC is a dungeon boss with no world coords, get_npc_coords falls back to the dungeon entrance (DUNGEON_ENTRANCES maps ~30 Classic + TBC instances).
• Sentinel-coord filter: instance NPCs without world coords are skipped at spawn-extraction time.

Quality report

1. Snapshot Headline — the seven KPIs that matter for diff comparisons (global score, efficiency, distance, jumps, absorption rate, lost quests, sub-guide count).
2. Faction comparison — diff-relevant columns per faction.
3. Per-faction detail — sub-guide table sorted by score.
4. Faction ranking by rep / distance.
5. Top 20 sub-guides by score.
6. Bottom 20 sub-guides (optimisation candidates).
7. Input data — static quest counts (sanity check).

CLI

• python create.py — interactive faction + expansion selection.
• python create.py --faction <id|name> — single faction.
• python create.py --all — bulk run across all factions; writes the quality report.

Versioning