Feature/strategic economy second act

AGENTS.md

@@ -92,6 +92,19 @@ After coding, provide:
 - If the user invokes `/backlog-execute [N]`, treat it as an execution command, not a planning request: default `N=5`, run `tools/backlog ready N`, pick that batch as the active queue, and begin execution under the backlog dependency, worktree, feature-branch, and finish-or-split rules.
 - For `/backlog-execute [N]` with parallel subagents, create one dedicated worktree and one dedicated feature branch per task before any edits. For dependency chains, complete the first task and branch the dependent task from the updated tip of the first task branch.
 
+Documentation index for agents:
+- `docs/README.md` - top-level documentation index.
+- `docs/STATUS.md` - current developer status, known open areas, and live system references.
+- `docs/CONTRIBUTING.md` - contribution, verification, and review flow.
+- `docs/DEVELOPMENT.md` - codebase map, hot spots, and validation shortcuts.
+- `docs/TOOLS.md` - local tools, context proxy, backlog helper, and repo skills.
+- `docs/BANNERMOD_BACKLOG.sqlite` - canonical backlog; use `tools/backlog`, not raw SQLite reads/writes.
+- `docs/BANNERMOD_TECHNICAL_DESIGN.md` - architecture, state model, authority model, invariants, and target end state.
+- `docs/STRATEGIC_ECONOMY_INTEGRATION.md` - VenaTerra-backed strategic economy, mine-site, yield, backlog, and verification notes.
+- `docs/AI_MINECRAFT_UI_STYLE_GUIDE.md` - required style rules for Minecraft-native UI/HUD work.
+- `MULTIPLAYER_GUIDE_RU.md` / `MULTIPLAYER_GUIDE_EN.md` - player-facing guides; update them for shipped player-visible mechanics.
+- `docs/BANNERMOD_ALMANAC.html` - compact player almanac; update it with player-facing UI/mechanic changes.
+
 12. Minecraft UI design
 - For Minecraft GUI/HUD work, load and apply the repo skill `minecraft-ui-design` from `.agents/skills/minecraft-ui-design/SKILL.md`.
 - UI must be Minecraft-native, minimal, readable, server-authoritative for gameplay mutations, localized, and checked for overlap with hotbar/chat/crosshair/boss bars/existing BannerMod overlays.

MULTIPLAYER_GUIDE_EN.md

@@ -144,6 +144,8 @@ Messenger, noble-trade, governor, patrol, and scout screens now keep their prima
 
 The logistics panel also labels the settlement's strategic role and route cost. Farms plus storage can make a surplus hub, market plus routes can make a junction market, fort plus route storage can make a chokepoint fort, and ports/water access become a water gate. Landlocked settlements with food or material production may show a specialty such as preserved food or worked materials. These labels are warnings and planning hints first: they expose logistics objectives and loyalty pressure before applying destructive penalties.
 
+Strategic economy status now treats the starter fort as level 1 and exposes the next fort-level requirements in food, iron, wood, stone, and coins through server status/debug output. Mines are not infinite passive income: a mine with no assigned worker, missing food, missing wood supports, missing tools, or a reserved disruption pressure can show degraded yield. Server-side NPC demand contracts can appear even with one player online; markets and trading posts improve their cadence or quality. Use `/bannermod economy contracts <claimUuid>` for the server-backed contract list, or the admin debug economy commands for deeper inspection.
+
 ### Code-backed settlement mechanics reference
 
 The settlement stack is not a single magic block. It is a pipeline of records and snapshots:

MULTIPLAYER_GUIDE_RU.md

@@ -163,6 +163,8 @@ BannerMod добавляет поселения, рабочих, армии, г
 
 Панель логистики также показывает стратегическую роль поселения и стоимость снабжения. Фермы плюс склад могут стать surplus hub, рынок плюс маршруты — junction market, форт плюс маршрутный склад — chokepoint fort, а порт/доступ к воде — water gate. У landlocked-поселений с едой или материалами может появиться специализация вроде preserved food или worked materials. Это сначала подсказки и предупреждения: они показывают логистические цели войны и давление на лояльность до жестких штрафов.
 
+Стратегическая экономика теперь считает стартовый форт уровнем 1 и через серверный статус/debug показывает требования к следующему уровню в еде, железе, дереве, камне и монетах. Шахты больше не считаются бесконечным пассивным доходом: если нет назначенного работника, еды, деревянных крепей, инструментов или действует зарезервированное давление нарушения, добыча может стать degraded. NPC-контракты спроса могут появляться даже при одном игроке онлайн; рынок и торговый пост улучшают частоту или качество таких контрактов. Список серверных контрактов смотри командой `/bannermod economy contracts <claimUuid>`, а глубокую проверку — через admin debug economy команды.
+
 ### Справочник механик поселения по коду
 
 Поселение — это не один магический блок, а цепочка записей и снапшотов:

docs/BANNERMOD_ALMANAC.html

@@ -92,6 +92,7 @@ <h3>Land and sea logistics</h3>
           <p>Long land routes may use a nearby approved free mount. If no mount is available, the courier continues on foot. Sea routes can use compatible ship carriers when available; the governor logistics mirror shows route id, carrier id or unassigned, phase, cargo progress, and blocked reason.</p>
           <h3>Taxes and strategy</h3>
           <p>Read tax lines as collected / due. Paid taxes fund the treasury; unpaid taxes show why payment failed and may stall upkeep or defense funding. Strategic labels such as surplus hub, junction market, chokepoint fort, and water gate are derived from real settlement conditions, not decorative text.</p>
+          <p>Starter forts begin at strategic fort level 1. Server status/debug output shows the next level's food, iron, wood, stone, and coin requirements plus current caps. Mines need assigned workers and basic support inputs; missing food, wood supports, tools, or reserved disruption pressure can degrade strategic yield. NPC demand contracts are server records, can spawn with one player online, and improve when the claim has a market or trading post. Use <code>/bannermod economy contracts &lt;claimUuid&gt;</code> to inspect them.</p>
           <p>Messenger, governor, noble-trade, patrol, and scout screens now carry their own status ribbon. Read it before closing the screen: it tells you whether you still need a recipient, contract, route, or other requirement, and it also confirms when the order was accepted and sent onward.</p>
         </article>
       </section>
@@ -237,6 +238,7 @@ <h3>Суша и вода</h3>
           <p>На длинных сухопутных путях перевозчик может автоматически сесть на ближайшее свободное разрешённое животное. Если такого нет, он идёт пешком. Морские пути могут использовать совместимые суда, если они есть; в сведениях правителя показываются номер пути, судно или отсутствие судна, этап, ход груза и причина остановки.</p>
           <h3>Налоги и стратегические роли</h3>
           <p>Налоги читаются как «собрано / требуется». Оплаченные налоги пополняют казну; неоплаченные показывают причину и могут остановить жалованье или оборонные расходы. Роли «избыточный пищевой узел», «рыночная развилка», «пограничный форт» и «водные ворота» берутся из реальных условий поселения.</p>
+          <p>Стартовый форт начинает как стратегический форт уровня 1. Серверный статус/debug показывает требования следующего уровня в еде, железе, дереве, камне и монетах, а также текущие лимиты. Шахтам нужны назначенные работники и базовое снабжение; нехватка еды, деревянных крепей, инструментов или зарезервированное нарушение снижают стратегическую добычу. NPC-контракты спроса хранятся на сервере, могут появляться при одном игроке онлайн и становятся лучше у клейма с рынком или торговым постом. Проверяйте их через <code>/bannermod economy contracts &lt;claimUuid&gt;</code>.</p>
         </article>
       </section>
 

docs/README.md

@@ -10,8 +10,12 @@ This directory contains active module documentation. Root-level Markdown is inte
 - `STATUS.md` - current developer-facing project status.
 - `CONTRIBUTING.md` - contribution flow for developers and agents.
 - `DEVELOPMENT.md` - codebase map, hot spots, and validation shortcuts.
+- `BANNERMOD_TECHNICAL_DESIGN.md` - architecture, state model, authority model, invariants, and target end state.
+- `STRATEGIC_ECONOMY_INTEGRATION.md` - VenaTerra-backed strategic economy and mine integration notes.
+- `AI_MINECRAFT_UI_STYLE_GUIDE.md` - style rules for Minecraft-native GUI/HUD work.
 - `BANNERMOD_BACKLOG.sqlite` - canonical unfinished-work queue; use `../tools/backlog` to inspect or update it.
 - `BANNERMOD_BACKLOG.md` - short pointer to the SQLite backlog and tool commands.
+- `BANNERMOD_ALMANAC.html` - compact player-facing almanac derived from the guides and current runtime state.
 - `TOOLS.md` - local developer tools, including the context proxy multitool.
 - Agent guardrail hooks/plugins are documented in `TOOLS.md` and live under `tools/agent-hooks/`, `.codex/`, and `.opencode/`.
 

docs/STATUS.md

@@ -1,6 +1,6 @@
 # Developer Status
 
-Last updated: 2026-04-28.
+Last updated: 2026-05-10.
 
 ## Runtime State
 
@@ -34,12 +34,14 @@ Last updated: 2026-04-28.
 - War-state sync now uses dirty/version tracking and cached payloads instead of serializing all war records every idle second for hash polling.
 - True-async pathfinding now checks scheduler capacity before snapshot capture and rejects over-budget snapshots with profiling counters.
 - GameTests are being hardened around claim worker growth, dedicated-server ownership, player cycle, settlement degradation, and upkeep currency sourcing.
+- Strategic economy second-act groundwork is in progress on `feature/strategic-economy-second-act`: VenaTerra now exposes a read-only deposit survey API in `/home/kaiserroman/venaterra`, BannerMod has an optional reflection bridge, claim-level food/iron/wood/stone/coin summary hints, strategic mine site records, mine maintenance/degraded-yield pressure, fort level/cap/readiness output, persisted NPC demand contracts, server-authoritative strategic resource accounting, and economy debug/status commands. See `docs/STRATEGIC_ECONOMY_INTEGRATION.md`.
 
 ## Known Open Areas
 
 - Full settlement onboarding remains incomplete: a new player still needs clearer starter-fort/town-hall, surveyor, wand, citizen, and profession guidance in-game.
 - Worker assignment binding is split between two sources of truth: the entity-side `currentWorkArea` (cached on `AbstractWorkerEntity`) and the registry-side `ValidatedBuildingRecord` in the settlement validated-building registry. The remaining gap is making `ValidatedBuildingRecord` the authoritative assignment source and reducing `currentWorkArea` to a derived runtime cache.
 - Sea-trade production/consumption is documented as hints, but not yet a full gameplay loop.
+- Strategic mine output is still a summary/read-model hint only and does not yet mutate storage, treasury, or item stacks. Fort caps are defined and exposed but not enforced at all creation/assignment points, and strategic resource accounting is available as a backend for later upgrade, contract, treaty, and upkeep callers.
 - Remaining war gaps are depth/coverage gaps, not absent systems: some outcomes are still command/admin-heavy, occupation control is lighter than a full governance loop, revolt resolution depends on objective presence rather than a richer objective campaign, siege-standard AI is basic attack/escort behavior, and morale plus ranged-backline polish still need follow-up.
 - `verifyGameTestStage` last had a known failure around `reconnectedOwnerRecoversAuthorityAfterOwnershipRoundTrip` in a Better Combat-present smoke; do not claim full GameTest green until rerun successfully.