# Subnautica2Maps SDK Clean Repair Brief

- task_id: `t_7af33592`
- owner: 墨策
- date: 2026-05-20
- project_slug: `subnautica2maps`
- new_tenant: `site-rerun-subnautica2maps-20260520-stitch-sdk-clean`
- previous_tenant: `site-rerun-subnautica2maps-20260520-clean`
- clean_rerun: true
- scope: narrow repair brief; not full keyword research; not full PRD rewrite
- output: `reports/site-pipeline/site-rerun-subnautica2maps-20260520-stitch-sdk-clean/subnautica2maps/repair-brief.md`

## 0. Decision

Repair verdict: `DESIGN_REPAIR_REQUIRED`.

Do not rerun market research or rebuild product strategy. The product remains a fan-made Subnautica 2 interactive map + resource locator + current-position route helper. The clean rerun starts from design because the prior design/frontend path was contaminated by a non-official Stitch tool path and local fallback artifacts.

This brief is the new working source for SDK clean design and frontend rebuild. Old PRD may be used only as history/context; old design HTML/screens/dist/repo must not be used as source input.

## 1. History-only / allowed inputs

### 1.1 History-only; do not use as source truth

- Old PRD v1: `/root/.hermes/kanban/boards/site-factory/workspaces/t_43537dda/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/03-prd-v1.md`
  - Use only to understand previously locked product intent and copy boundaries.
  - Do not treat as the active handoff if this repair brief conflicts with it.
- Old design package: `/root/.hermes/kanban/boards/site-factory/workspaces/t_f6e7a59a/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/design`
  - Quarantined/history-only.
  - Do not reuse HTML/CSS/screens/components.
- Old frontend repo/dist: archived from `/root/projects/subnautica2maps` and `/root/.hermes/kanban/boards/site-factory/workspaces/t_883d0c5a/dist`.
  - Do not use as implementation source.

### 1.2 Active stable contracts

Use these stable completed artifacts as inputs:

1. Stitch SDK root cause:
   - `/root/.hermes/reports/stitch-sdk-root-cause-20260520.md`
2. Clean reset plan:
   - `/root/.hermes/reports/subnautica2maps-stitch-clean-reset-plan-20260520.md`
3. Delete/quarantine manifest:
   - `/root/.hermes/reports/clean-rerun-subnautica2maps-20260520-stitch-sdk-delete-manifest.json`
4. Public-reference data contract:
   - `/root/.hermes/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/data-public-reference/markers.public.v20260520.json`
   - `/root/.hermes/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/data-public-reference/manifest.json`
   - `/root/.hermes/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/data-public-reference/frontend-contract-public-reference.md`
   - `/root/.hermes/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/data-public-reference/index-coverage-public-reference.json`
5. Media/assets + compliance strategy:
   - `/root/.hermes/kanban/boards/site-factory/workspaces/t_bc0c998c/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/media/media-assets.json`
   - `/root/.hermes/kanban/boards/site-factory/workspaces/t_bc0c998c/reports/site-pipeline/site-rerun-subnautica2maps-20260520-clean/subnautica2maps/media/media-compliance-report.md`
6. Current SDK clean carry-forward manifest task:
   - `t_8bae1f08` is expected to produce `data-assets-carry-forward.json`.
   - 墨影 can start only when both this brief and `t_8bae1f08` are done, because `t_c3810340` depends on both.

## 2. Product repair boundary

Keep:

- Fan-made interactive Subnautica 2 map.
- Resource/POI/blueprint/data box locator.
- Current-position route helper.
- Local progress tracking without login.
- Mobile-first map lookup.
- Source/confidence/index-policy transparency.
- Fan-made/no-affiliation legal posture.

Do not add:

- Login, Stripe, subscription, paywall.
- Community submissions.
- Cross-device sync.
- Admin CMS.
- Official-looking companion app branding.
- Official logos, key art, screenshots, map tiles, icons, favicon, OG art.
- Copied competitor tiles/data/text/visual system.
- Claims like official, endorsed, approved, complete, all locations, 100% accurate.

## 3. Page and state list for new Stitch design

墨影 must create official Stitch SDK screens for the following. Each screen needs `projectId`, `screenId`, `htmlUrl`, `imageUrl`, downloaded HTML, downloaded image, and run log.

### 3.1 Required pages/templates

1. Homepage `/`
   - Hero with embedded map/search entry.
   - Quick chips: silver, copper, sulfur, black boxes, data boxes, Old Habitat, Camp One.
   - Map preview with HUD/scanner feel.
   - Route helper teaser.
   - Data trust block: public reference, Early Access warning, confidence labels.
   - Fan-made/no-affiliation notice visible.

2. Map tool `/map`
   - Full map canvas/panel.
   - Search bar.
   - Category filters.
   - Result count.
   - Marker list/sidebar.
   - Marker detail panel.
   - Route helper panel.
   - Local progress state.
   - Source/confidence legend.

3. Resource page template `/resources/{slug}`
   - Example P0 resources: silver, copper, sulfur.
   - Short answer first.
   - Related markers list.
   - Coordinates/depth/biome table.
   - Source attribution cards.
   - Optional 1-2 safe media cards after primary data.
   - CTA back to `/map` with prefilled search/filter.

4. Location/POI/Black box template
   - Example: Old Habitat, Camp One, Black Boxes.
   - Marker clusters.
   - Route/context notes.
   - Source/confidence status.
   - Optional lazy YouTube/source card if allowed.

5. Guide template
   - Example: `does Subnautica 2 have a map`, `how to find coordinates`.
   - Answer-first content.
   - Map CTA.
   - Explainer cards.
   - No heavy media above core answer.

6. Legal/support pages visual shell
   - Privacy, Terms/Legal, Contact/DMCA.
   - Need fan-made disclaimer and embedded-media/cookie note if YouTube ships.

### 3.2 Required interaction states

Design must cover these states, not only static pages:

- Map loading / data loaded.
- Empty map with zero selected filters.
- Search active with result count and highlighted markers.
- No results state.
- Filter selected: Resources, Blueprints, Data Boxes, Wildlife, Plants, Biomes, Locations.
- Marker detail open.
- Low-confidence or limited-index marker warning.
- Source attribution visible.
- Current position not set.
- Current position set.
- Route result: direction, distance, depth delta, route note, confidence.
- Route invalid state.
- Local progress found/collected checked.
- Mobile bottom sheet collapsed.
- Mobile bottom sheet expanded with marker detail.
- Mobile route helper state.

## 4. Core user tasks / acceptance tests

A design or frontend implementation is not acceptable unless these tasks are visibly supported:

1. Find silver quickly
   - User opens `/map`, searches `silver`, sees matching markers, opens one result, sees coordinates/depth/source/confidence.

2. Filter resource markers
   - User toggles Resources, sees result count change, keeps map usable.

3. Open a marker detail
   - User clicks/taps marker, sees name/type/category, coordinates, depth, biome/region, source, confidence, updated/retrieved date, Early Access warning.

4. Calculate a route hint
   - User enters current X/Y/Z or depth, selects a target marker, receives approximate direction, distance, depth delta, route note, and confidence.
   - Raw current coordinates must not be sent to analytics.

5. Track local progress
   - User marks a marker found/collected; state is visually distinct and local-only.

6. Use on mobile while playing
   - At 360-390px width, search/filter/detail/route can be completed without horizontal overflow or map being permanently covered.

7. Understand trust status
   - User can distinguish indexable/corroborated/public-reference/limited-index markers and sees no-affiliation disclaimer.

8. Reach a source safely
   - User can click source attribution/outbound guide links; YouTube embeds only load after click and only via `youtube-nocookie.com`.

## 5. Competitive baseline

Search intent remains tool-seeking: players want an interactive map, resource/POI lookup, coordinates/depth, route hints, and mobile lookup. A landing page without a real map fails.

### 5.1 Minimum competitors imply

| Competitor | Visible baseline | Required response |
|---|---|---|
| IGN | High-authority guide hub, interactive-map framing, resource pages | Answer-first guide/resource pages + map CTA + source links |
| Game8 | Coordinates/depth/region/biome and Early Access notice | Marker detail must include coordinates/depth/biome/source/confidence |
| MapGenie | Pan/zoom, filters, search, progress, mobile, upsell | We need pan/zoom/search/filters/progress/mobile, without login pressure |
| GamesDB | Route/current-position framing, categories, resource/POI coverage | Route helper must be visible and testable |
| YouTube/Steam/Reddit | Discovery and proof of player tasks | Use as outbound/corroboration/support, not copied content |

### 5.2 Competitive minimum for DESIGN_GO

- Self-made underwater map base, not a SaaS landing page and not a generic rectangle grid.
- Pan/zoom affordances are obvious.
- Markers are visually grouped by category.
- Search/filter/list/detail relationship is clear.
- Current-position route helper has a real UI, not just copy.
- Mobile bottom sheet is designed as a first-class state.
- Source/confidence/EA warning is built into marker detail and pages.
- Fan-made/no-affiliation is visible but not disruptive.

## 6. Data and asset inventory references

### 6.1 Public-reference marker contract

Current stable data summary:

- marker_count: 63
- confirmed_public_reference_count: 30
- corroborated_count: 33
- needs_verification_count: 0
- indexable_count: 13
- limited_index_count: 50
- launch_data_ready_public_reference: true
- seo_index_ready_limited: true

Marker types:

- resource: 18
- poi: 16
- data_box: 26
- location: 3

Design/frontend must read fields from the public-reference contract:

- `marker_id`, `name`, `type`, `category`, `subtype`
- `coordinates.x/y/z/raw/system/precision`
- `depth.value_m/source/precision`
- `region`, `biome`, `resource_types`
- `description`, `route_note_from_lifepod`, `route_note_from_current_position_template`
- `prerequisite_gear`, `nearby_resources`, `nearby_poi`
- `verified_game_version`, `source_type`, `confidence`, `source_name`, `source_url`, `retrieved_at`, `source_confidence`, `license_note`, `provenance`
- `index_policy`, `index_policy_reason`, `sitemap_eligible`

Source attribution label:

`Public reference: {source_name} · retrieved {retrieved_at} · confidence {confidence}`

Limited-index warning:

`This marker is suitable for the map, but not enough for a standalone indexed detail page yet.`

### 6.2 Media/assets contract

Current stable media summary:

- media_assets: 13
- youtube_guide: 8
- article_reference: 2
- official_press_asset_inventory: 1
- official_store_reference: 1
- community_reference: 1
- verdict: `GO_WITH_CONSTRAINTS`

Product-first media defaults:

- The site must feel useful to players, not like a legal memo or placeholder shell.
- Do **not** rely on generated neutral SVG placeholders as the primary visual experience. Placeholders are allowed only as temporary dev fixtures and must not pass Design Acceptance.
- Map base can be self-made, but it must be a credible playable tool surface: biome-like terrain shapes, depth/coordinate layers, resource clusters, sonar/HUD treatment, category icons, and pan/zoom affordances. A bare SVG grid is not enough.
- Use real player-valuable media where it is safe and useful:
  - YouTube guide embeds via `youtube-nocookie.com`, lazy/click-to-load; the thumbnail may be provided by the YouTube embed/player rather than rehosted locally.
  - Outbound source cards to IGN/Game8/wiki/community/official pages with original summaries and attribution.
  - Text citations and source links are fine; copied prose/data dumps are not.
- For game atmosphere, prioritize generated or self-authored **underwater ambience / scanner UI / stylized map art** plus real embedded guides. Do not pretend generated SVG placeholders are game素材.

Safety red lines:

- No rehosting/downloading third-party YouTube footage or thumbnails into our repo/CDN.
- No use of official logos/key art/screenshots/OG/favicons as our branding, hero art, favicon, or local assets unless a clearly licensed/press-kit allowance is verified and cited.
- No copied IGN/Game8/MapGenie/GamesDB/Fandom/Reddit/Steam text, marker data dumps, screenshots, icons, or map tiles.
- No claim of official/endorsed/complete/100% accurate. Keep a visible fan-made disclaimer, but do not let compliance copy dominate the product experience.

Recommended first placements:

- `/resources/silver`: ChemicalApes silver video + IGN silver article.
- `/black-boxes`: all black boxes video.
- Old Habitat detail/guide: Old Habitat entry + Blackbox Quaker card.
- `/resources/lithium`: P1/noindex until marker data is indexable.

## 7. Map interaction acceptance

### 7.1 Design acceptance hard gate

`DESIGN_GO` requires all of the following:

- Official SDK path only: `@google/stitch-sdk`.
- Model uses current supported model, e.g. `GEMINI_3_FLASH` or `GEMINI_3_1_PRO`; do not use deprecated `GEMINI_3_PRO`.
- Evidence exists for each required screen/state:
  - `stitch/screen-index.json`
  - `html/*.html`
  - `screens/*.png|jpeg`
  - `stitch/run.log`
  - `verification.json`
- `screen-index.json` includes real `projectId`, `screenId`, `htmlUrl`, `imageUrl`.
- Downloaded HTML contains `<html` and real CSS/Tailwind/design system content.
- Downloaded image files are valid PNG/JPEG.
- No `local-html-fallback` is marked as Stitch success.
- Visual direction is game/map-specific: underwater, HUD/scanner, coordinate/depth, sonar/grid, biome/resource layer feel.
- Map states are designed, not merely described.

### 7.2 Frontend acceptance hard gate

Frontend cannot pass unless:

- It reads the public-reference marker contract or the new `data-assets-carry-forward.json` from `t_8bae1f08` once available.
- It does not infer data from prose reports.
- It implements real pan/zoom or at minimum a credible map interaction layer with map movement affordances; a static image/panel is not enough.
- It implements search/filter/result count/detail/route/progress/mobile bottom sheet.
- It shows source/confidence/index policy in marker detail.
- It uses no unauthorized local/rehosted official/competitor visual assets as branding or map tiles; it may use safe embedded YouTube guides and outbound source cards when attributed and lazy-loaded.
- It keeps `/map` free of heavy video iframes above core map experience.
- It tracks required events without sending raw current coordinates.

### 7.3 SEO/index acceptance hard gate

- `/` and `/map` can be indexable only when the tool is actually usable.
- Resource/location/marker-backed pages can be indexable only when `index_policy === "index"`, content is unique, and source/confidence/freshness is visible.
- `limited_index` markers are usable inside map/list/detail but should not automatically create standalone sitemap URLs.
- Placeholder, partial, query, local-state, search-result, route-result, and thin pages must be noindex and excluded from sitemap.

## 8. Copy and visual constraints

### 8.1 Primary copy direction

H1 direction:

`Find Subnautica 2 Resources Faster`

Subhead direction:

`Search a fan-made interactive map for resources, POIs, blueprints, biomes, and route hints from your current position.`

Primary CTA:

`Open the Map`

Secondary CTA:

`Find a Resource`

Fan-made notice:

`Fan-made player utility. Not affiliated with Unknown Worlds, KRAFTON, or the Subnautica franchise.`

### 8.2 Required footer/legal disclaimer

`Subnautica2Maps is a fan-made player tool and is not affiliated with, endorsed by, sponsored by, or approved by Unknown Worlds Entertainment, KRAFTON, or the Subnautica franchise. SUBNAUTICA and UNKNOWNWORLDS are trademarks or registered trademarks of Unknown Worlds Entertainment, Inc. All trademarks belong to their respective owners.`

### 8.3 Visual direction

Use:

- Dark underwater ambience.
- Teal/cyan/green bioluminescent accents.
- HUD/scanner panels.
- Coordinate/depth readouts.
- Sonar/radar/grid lines.
- Layer chips for resources/POIs/blueprints/data boxes/biomes.
- Self-made schematic terrain/biome shapes, not copied tiles.

Avoid:

- Generic SaaS dashboard.
- Official Subnautica logo/key art/screenshots.
- Overly polished official companion look.
- Marketing blocks that push the map below the fold.
- Heavy YouTube/article cards in `/map` first viewport.

## 9. Handoff to 墨影 / moying

Task: `t_c3810340` — official Stitch SDK high-fidelity redesign.

Inputs to read:

1. This brief.
2. `/root/.hermes/reports/stitch-sdk-root-cause-20260520.md`
3. `/root/.hermes/reports/clean-rerun-subnautica2maps-20260520-stitch-sdk-delete-manifest.json`
4. `t_8bae1f08` carry-forward manifest when done.
5. Public-reference data contract and media/compliance artifacts listed in section 1.2.

Deliverables required from moying:

- `design/HANDOFF.md`
- `design/stitch/screen-index.json`
- `design/stitch/run.log`
- `design/html/*.html`
- `design/screens/*.png|jpeg`
- `design/verification.json`
- Screen set must include homepage, map normal, map search/filter, marker detail, route helper, mobile bottom sheet, resource page template, guide/detail template.

Blocking conditions:

- Any use of `@_davideast/stitch-mcp tool ...` as production path.
- Any missing projectId/screenId/htmlUrl/imageUrl evidence.
- Any local-html-fallback marked as DESIGN_GO.
- Any design without game/map atmosphere.
- Any design that lacks map interaction states.
- Any design that over-rotates into compliance disclaimers or placeholder-safe art instead of a useful game map product.
- Any primary media/visual treatment based on generic SVG placeholders rather than credible underwater/scanner/map atmosphere plus real embedded/source media where useful.

## 10. Handoff to 墨枢 / moshu

Task: `t_8bae1f08` — data/assets carry-forward manifest.

Expected output:

- `data-assets-carry-forward.json`
- marker/api contract paths
- source/provenance/confidence/index_policy
- YouTube/media thumbnail inventory and legal fallback strategy

Moshu should preserve only stable contracts:

- Public-reference dataset with 63 markers.
- Index policy and frontend contract.
- Media-assets JSON and compliance report.
- No old dist/repo/design HTML/screens.

Moshu should explicitly mark:

- `ui_fixture_ready=true`
- `launch_data_ready_public_reference=true`
- `seo_index_ready_limited=true`
- `confirmed_public_reference_count=30`
- `corroborated_count=33`
- `indexable_count=13`
- `limited_index_count=50`

## 11. Downstream gate sequence

Canonical SDK clean path:

1. `t_7af33592` 墨策 repair brief — this task.
2. `t_8bae1f08` 墨枢 carry-forward manifest.
3. `t_c3810340` 墨影 official Stitch SDK design.
4. `t_56f19add` 墨策 Design Acceptance.
5. `t_4e720fda` 墨界 frontend rebuild from new Stitch truth + data contract.
6. `t_d54ed9f8` 墨引 SEO/GEO/AEO recheck.
7. `t_d0cb5ee8` 墨盾 compliance/IP/material recheck.
8. `t_a7f3efac` 墨策 Product Acceptance.
9. `t_8b3bd292` 墨测 final QA.
10. `t_208b5a7d` 墨运 launch only after PM_GO + QA_GO.

No downstream worker should treat the old DESIGN_GO or old frontend deployment as valid evidence for this clean rerun.