Studio Hathor · Geography Modeling

Purpose#

Admin lane console for the real @hathor/domain-models region geography scorers. Submit a region (terrain coverage, danger level + sources, biome, flora/fauna diversity, exploration status) and read back travel speed, composite danger, biodiversity, exploration level, and dominant terrain. Admin-scoped and fail-closed.

Entry points#

• Quick-action link from /studio/hathor/world-configuration (this page links out to world-configuration)
• Direct URL / bookmark — yes; alternates.canonical set
• Studio overview — see ../../studio-overview.md

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace <section data-hathor-geography-modeling-workspace>:
  • <h1> (WorkspaceHeading) "Hathor Geography Modeling Workspace"
  • Summary <p data-hathor-geography-modeling-summary>
  • Region Analysis Lane (<h2 data-geo-lane-heading>) — the analyze form data-geo-form
• Route Map panel (data-hathor-geography-modeling-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_GEOGRAPHY_MODELING_ROUTE_MAP
• Quick-action lane: two Link.quickAction anchors — World Configuration, Back to Studio workspace index

States#

• Loading — <p data-geo-loading> while the GET request is in flight
• Unauthorized — data-geo-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-geo-error on non-OK GET / malformed catalog
• Ready (form) — data-geo-form once the enum catalog loads
• Result — data-geo-result after a 200 analyze; data-geo-analyze-error for invalid JSON / non-200

Interactions#

Region Analysis Lane#

• Region (JSON) — <textarea data-geo-payload> (aria-label "region json"); accepts { region:{ name, terrain[{ type, coverage }], dangerLevel, dangerSourceCount, biome?, floraDiversity, faunaDiversity, explorationStatus } }
• Reference enums — data-geo-enums
• Analyse region — <button data-geo-submit type="submit"> → POST /v1/admin/hathor/workbench-worlds/analyze
• Result — data-geo-headline plus data-geo-scores with per-metric data-geo-score rows (travel speed, danger, biodiversity, exploration, dominant terrain)

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_GEOGRAPHY_MODELING_ROUTE_MAP

Quick-action lane#

• "Open Hathor World Configuration workspace" (→ /studio/hathor/world-configuration)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/workbench-worlds (note: the geography lane reuses the workbench-worlds endpoint, not a geography-modeling slug) on mount
• Writes: POST /v1/admin/hathor/workbench-worlds/analyze
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: admin-scoped fail-closed (401/403); behind the signed-in
  • studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-workbench-dashboard.md (rolls the same region scorers into a world overview), ./studio-hathor-location-modeling.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorGeographyModelingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorGeographyModelingRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/* admin lane consoles ship in V1.
• The lane reads/writes the workbench-worlds endpoint rather than a dedicated geography-modeling slug; confirm whether that sharing is intentional or a slug that should be renamed.
• Route Map advertises continents/, nested regions/biomes/, and governance/ sub-routes with no page.tsx yet.