release: bump version to 0.49.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-08 17:42:27 +08:00
parent bb9183b8a4
commit e1984c7a35
86 changed files with 9165 additions and 412 deletions
--- a/docs/technical/en/README.md
+++ b/docs/technical/en/README.md
@@ -25,8 +25,12 @@ What belongs here:

 - [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md): The shortest path to getting Planet running from scratch
 - [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md): Complete usage guide for the console, `planet.sh`, Earth, and Docs
+- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md): Collect and preview coordinate candidates for compute centers and BGP collectors on Earth
 - [Collector Settings and Connectivity Validation](/home/ray/dev/linkong/planet/docs/technical/en/datasource-collector-settings-connectivity.md): Data source catalog, collector settings, connectivity validation, and BarentsWatch credentials
+- [Shared Location Resolution Pipeline Development Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-development.md): Backend location resolver / pipeline interfaces, registries, and extension points
+- [Docs Gatekeeper Development Guide](/home/ray/dev/linkong/planet/docs/technical/en/docs-gatekeeper-development.md): Backend Docs catalog, Markdown content loading, and Gatekeeper permission groups
 - [Earth Interactable Usage](/home/ray/dev/linkong/planet/docs/technical/en/earth-interactable-usage.md): API, lifecycle, and integration examples for Earth surface icon Interactable
+- [Earth Toolbar and Overlay Coordination](/home/ray/dev/linkong/planet/docs/technical/en/earth-toolbar-overlay-coordination.md): Closing matrix and integration rules for toolbar buttons, search, settings, news, and layer overlays

 What does not belong here:

--- a/docs/technical/en/backend-collectors.md
+++ b/docs/technical/en/backend-collectors.md
@@ -87,6 +87,10 @@ async def run(self, db):
 | BarentsWatch AIS | vessel | AIS vessel positions, speed, heading, MMSI, and related fields | Collector settings |
 | AISStream Vessels | vessel_ais | AIS WebSocket realtime stream, written to the raw observation layer and displayed through aggregation | Collector settings |

+AIS vessel collectors use a different persistence path from regular `CollectedData` collectors. BarentsWatch, AISStream, and custom `vessel_ais` sources write into the AIS raw observation layer first, then the aggregation service merges those observations into the GeoJSON and detail payloads used by the Earth vessel layer. This preserves source, transport, field conflicts, and observation time instead of letting one realtime source overwrite the final display table.
+
+TOP500 and Epoch AI compute sources do not always provide usable coordinates. The unified Earth compute-center endpoint uses only valid source-provided coordinates or `compute_center_locations` dimension-table coordinates during the main map startup path; records without coordinates are returned as `unresolved` instead of being rendered from a local registry, country centroid, or guessed city. When users manually collect candidates, the backend queries ROR and Nominatim/OpenStreetMap from source fields; accepted candidates are saved into `compute_center_locations` and rendered from that table on the next layer refresh.
+
 ## IV. Data Format (stored in CollectedData table)

 ```python
@@ -213,13 +217,136 @@ backend/app/services/collectors/
 ├── epoch_ai.py          # Epoch AI collector
 ├── huggingface.py       # HuggingFace collector
 ├── peeringdb.py         # PeeringDB collector
-└── telegeraphy.py       # TeleGeography submarine cable collector
+├── telegeraphy.py       # TeleGeography submarine cable collector
+├── vessel_ais.py        # BarentsWatch AIS vessel collector
+└── aisstream.py         # AISStream WebSocket vessel collector
+
+backend/app/services/
+├── custom_datasource_runtime.py      # Custom REST / WebSocket mapping runtime
+├── datasource_mapping.py             # Deterministic field mapping and target writes
+├── vessel_ais_aggregation.py         # AIS raw observation writes and aggregate reads
+├── vessel_aggregation_strategy.py    # Multi-source field selection, freshness fallback, and conflict records
+└── vessel_enrichment.py              # Vessel profile enrichment cache

 backend/app/models/
-└── collected_data.py    # Unified data model
+├── collected_data.py           # Unified data model
+└── vessel_enrichment.py        # Vessel enrichment cache
 ```

-## IX. Data Usage
+## IX. Credentialed Collectors
+
+Some collectors require external service credentials:
+
+| Collector | Credential provider | Credential sources |
+| --- | --- | --- |
+| `barentswatch_vessels` | `barentswatch` | Console collector settings, environment variables, `~/.zshrc` |
+| `aisstream_vessels` | `aisstream` | Console collector settings, environment variables, `~/.zshrc` for connectivity checks; save it in collector settings or inject it into the backend environment for collection |
+| `spacetrack_tle` | `spacetrack` | Environment variables, `~/.zshrc` |
+
+### BarentsWatch AIS
+
+BarentsWatch AIS credential resolution is centralized in:
+
+- [barentswatch.py](/home/ray/dev/linkong/planet/backend/app/services/barentswatch.py)
+
+`VesselAISCollector` only collects and transforms AIS data. It no longer reads environment variables or builds token requests directly. It uses:
+
+- `resolve_barentswatch_config()`
+- `fetch_barentswatch_access_token()`
+
+Resolution priority:
+
+1. `DataSourceConfig.auth_config`
+2. `DataSourceConfig.config`
+3. Environment variables
+4. `~/.zshrc`
+
+Supported variables:
+
+```bash
+export BARENTSWATCH_CLIENT_ID="..."
+export BARENTSWATCH_CLIENT_SECRET="..."
+```
+
+Historical misspellings are also supported:
+
+```bash
+export BARRENTSWATCH_CLIENT_ID="..."
+export BARRENTSWATCH_CLIENT_SECRET="..."
+```
+
+Connectivity validation requests `https://id.barentswatch.no/connect/token` for an access token with `scope=ais`, then requests the AIS endpoint with `Authorization: Bearer <token>`.
+
+### AISStream Realtime Vessels
+
+AISStream uses the `wss://stream.aisstream.io/v0/stream` WebSocket endpoint. Its default runtime is a long-lived realtime collector rather than the traditional REST pattern of one request, progress to 100%, then completion.
+
+Runtime configuration:
+
+- `api_key`: read first from `DataSourceConfig.auth_config.api_key` or `config.api_key`; it can also come from the backend process environment variable `AISSTREAM_API_KEY`.
+- `bounding_boxes`: AISStream subscription bounds. The default example is global `[[[-90, -180], [90, 180]]]`; demos and production runs should usually start with a smaller area.
+- `message_types`: defaults to `PositionReport` and `ShipStaticData`.
+- `streaming_enabled`: enables long-lived streaming by default; disabling it falls back to batch-style `fetch -> transform -> save`.
+- `streaming_max_messages`: test-only stop limit. Non-zero values stop the stream after the requested number of messages.
+- `reconnect_delay_seconds` and `receive_timeout_seconds`: control reconnect delay and idle receive waits.
+
+State semantics:
+
+- `connecting`: connecting to AISStream.
+- `streaming`: receiving realtime messages; `records_processed` means messages seen, usually without a fixed total or percentage.
+- `reconnecting`: upstream or network interruption; the collector records `AISSourceHealth` and waits before reconnecting.
+- `stopped` / `cancelled`: stopped by a test limit or user action.
+
+AISStream connectivity validation reads the saved collector configuration, environment variables, and `AISSTREAM_API_KEY` in `~/.zshrc` through `datasource_connectivity.py`. For actual collection, the most reliable path is saving the API key in `Settings -> Collector Settings -> AISStream Vessels`; if the key only lives in `~/.zshrc`, confirm that the backend process inherited it.
+
+### AIS Raw Observations And Aggregation
+
+AIS observations do not directly replace final vessel records. They are first saved as raw observations:
+
+- `source` records the origin, such as `barentswatch_vessels`, `aisstream_vessels`, or a custom source name.
+- `delivery_mode` captures realtime quality; `realtime_stream` outranks `polling`.
+- `transport` records `websocket` or `http`.
+- Dynamic fields such as position, speed, and course are selected by freshness and source priority.
+- Static fields prefer non-empty values; conflicting candidates are recorded for detail and diagnostics views.
+
+Earth still reads vessel data from:
+
+```http
+GET /api/v1/visualization/geo/vessels
+GET /api/v1/visualization/vessels/{mmsi}
+GET /api/v1/visualization/vessels/{mmsi}/track
+GET /api/v1/visualization/vessels/{mmsi}/conflicts
+GET /api/v1/visualization/vessels/aggregation/diagnostics
+```
+
+`/geo/vessels` merges raw observation aggregation with the legacy BarentsWatch latest-position tables so adding AISStream does not hide historical BarentsWatch-only vessels.
+
+## X. Collector Settings And Connectivity Validation
+
+The console "Collector Settings" page owns endpoint, headers, timeouts, retries, and credentials for all built-in collectors. Connectivity is derived by the backend checksum rather than by frontend button styling:
+
+- endpoint
+- auth type
+- headers
+- config
+- credential provider
+- credential fingerprint
+
+Related APIs:
+
+```http
+GET  /api/v1/datasources/configs/all
+POST /api/v1/datasources/configs/builtin/connection-status
+POST /api/v1/datasources/configs/builtin/connect
+POST /api/v1/settings/integrations/barentswatch/connect
+GET  /api/v1/settings/credential-guides/{provider}
+POST /api/v1/settings/credential-guides/{provider}/generate
+POST /api/v1/settings/credential-guides/{provider}/reset
+```
+
+See [Collector Settings and Connectivity Validation](/home/ray/dev/linkong/planet/docs/technical/en/datasource-collector-settings-connectivity.md) for the full flow.
+
+## XI. Data Usage

 Collected data ultimately:

@@ -227,7 +354,7 @@ Collected data ultimately:
 2. **Situational analysis** — global compute distribution statistics and growth trends
 3. **Alert system** — detects changes to important nodes

-## X. Collector Registration
+## XII. Collector Registration

 Collectors are automatically registered at application startup:

@@ -249,7 +376,7 @@ collector_registry.register(TeleGeographyCableSystemCollector())

 **Core file**: `backend/app/services/collectors/registry.py`

-## XI. Triggering Collection
+## XIII. Triggering Collection

 ### Method 1: Scheduled

--- a/docs/technical/en/backend-datasources-api-performance.md
+++ b/docs/technical/en/backend-datasources-api-performance.md
@@ -0,0 +1,99 @@
+# DataSources List API Performance Optimization
+
+## Background
+
+`GET /api/v1/datasources` is the core API for the Data Sources page. Slow responses directly block page rendering.
+
+## Query Path Before Optimization
+
+`_load_datasource_list_context` used to run these queries sequentially:
+
+| Order | Function | Query | Bottleneck |
+| --- | --- | --- | --- |
+| 1 | `_load_latest_running_tasks` | `collection_tasks` window query; stale check depends on this result | Must be serial |
+| 2 | `_load_latest_completed_tasks` | `collection_tasks` window query for latest completed tasks | Serial wait |
+| 3 | `_load_datasource_data_counts` | `COUNT(*) GROUP BY source` on `collected_data` | Slow full-table scan |
+| 4 | `_load_datasource_endpoint_overrides` | Simple `datasource_configs` SELECT | Serial wait |
+
+## Phase 1: Parallelization
+
+The independent queries 2, 3, and 4 were moved to `asyncio.gather` with separate sessions:
+
+```python
+async def _fetch_completed():
+    async with async_session_factory() as s:
+        return await _load_latest_completed_tasks(s, datasource_ids)
+
+async def _fetch_counts():
+    async with async_session_factory() as s:
+        return await _load_datasource_data_counts(s, sources)
+
+async def _fetch_overrides():
+    async with async_session_factory() as s:
+        return await _load_datasource_endpoint_overrides(s, sources)
+
+completed_tasks, data_counts, endpoint_overrides = await asyncio.gather(
+    _fetch_completed(), _fetch_counts(), _fetch_overrides(),
+)
+```
+
+SQLAlchemy `AsyncSession` does not support concurrent use from multiple coroutines, so every parallel branch needs its own session.
+
+## Phase 2: Remove Heavy Queries
+
+### Remove `_load_datasource_data_counts`
+
+`data_count` was only used by the frontend to show an edge-case `(0 records)` hint in the latest collection column. It was not worth keeping a `COUNT(*) GROUP BY` full-table scan.
+
+- Frontend `(0 records)` display logic was removed.
+- `data_count` was removed from the `BuiltInDataSource` interface.
+
+### Remove `_load_latest_completed_tasks`
+
+`last_status` and `last_run_at` are already written to the `DataSource` model when collectors finish, so the list endpoint no longer needs to join `collection_tasks`:
+
+```python
+# Before: completed_tasks query required
+last_run_at = datasource.last_run_at or (last_task.completed_at if last_task else None)
+last_status = datasource.last_status or (last_task.status if last_task else None)
+
+# After: read model fields directly
+last_run_at = datasource.last_run_at
+last_status = datasource.last_status
+```
+
+`last_records_processed` was removed as well because it came from completed task rows and is not displayed in the list.
+
+## Query Path After Optimization
+
+```text
+datasources SELECT                     -> required primary data
+_load_latest_running_tasks             -> required for running state and stale check
+_load_datasource_endpoint_overrides    -> required for endpoint overrides and collector settings display
+```
+
+The endpoint now runs three queries instead of five. The last two run sequentially because running tasks are needed for stale checks and endpoint overrides are lightweight.
+
+## Frontend `triggerDatasource` Double Refresh Fix
+
+`triggerDatasource` previously called `fetchData()` twice:
+
+```typescript
+// Before
+} else {
+    window.setTimeout(() => { fetchData() }, 800)
+}
+fetchData()
+
+// After: mutually exclusive
+if (res.data.task_id) {
+    fetchData()
+} else {
+    window.setTimeout(fetchData, 800)
+}
+```
+
+## Related Files
+
+- [datasources.py](/home/ray/dev/linkong/planet/backend/app/api/v1/datasources.py): `_load_datasource_list_context`, `list_datasources`
+- [DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx): `BuiltInDataSource`, `triggerDatasource`
--- a/docs/technical/en/datasource-collector-settings-connectivity.md
+++ b/docs/technical/en/datasource-collector-settings-connectivity.md
@@ -62,7 +62,7 @@ File:
 Current behavior:

 - The `collector_credentials` tab is displayed as "Collector Settings".
- A select lists all built-in collectors.
+- A select lists built-in collectors and supports maintaining custom supplemental sources that merge into built-in data.
 - The only button beside the select is a plug icon for health checks.
 - Status tags below the select show:
  - `Credentials required` / `No credentials required`
@@ -72,6 +72,8 @@ Current behavior:
  - Whether the endpoint is overridden
 - Collectors that require credentials place the credential card above base configuration.
 - Collectors without credentials only show base configuration.
+- The AISStream collector uses WebSocket semantics: connecting, streaming, reconnecting, or stopped. It does not use a fixed completion percentage.
+- Custom source editing lives in collector settings. The data source catalog keeps overview, run controls, and read-only drawers.

 The connection button uses an inline Tabler-style plug icon with `plug-connected` semantics, avoiding the older refresh icon for a connection action.

@@ -284,6 +286,100 @@ Normalization:
 - Vessel type usually comes from lower-frequency `ShipStaticData.Type`; the backend maps AIS numeric type codes to Cargo / Tanker / Passenger / Fishing / Military.
 - If a vessel has not yet produced a static message, its aggregated type can still be `Other`; v5 vessel profile enrichment is planned to fill that gap.

+Connectivity validation reads saved configuration, environment variables, and `AISSTREAM_API_KEY` from `~/.zshrc`. For actual collection, prefer saving the API key in collector settings. If the key only lives in `~/.zshrc`, confirm that the backend process inherited it; otherwise validation may pass while the collector runtime cannot read the key.
+
+## Custom REST / WebSocket Mapping Runtime
+
+Files:
+
+- [custom_datasource_runtime.py](/home/ray/dev/linkong/planet/backend/app/services/custom_datasource_runtime.py)
+- [datasource_mapping.py](/home/ray/dev/linkong/planet/backend/app/services/datasource_mapping.py)
+
+Custom sources are supplemental inputs for existing target schemas, not isolated data islands. The most complete target today is `vessel_ais`: a custom REST or WebSocket source is mapped deterministically, written into AIS raw observations, and then pushed to Earth through the `vessels` WebSocket channel.
+
+### Configuration Semantics
+
+Important fields:
+
+- `source_type`: `rest` / `http` / `websocket` / `ws`.
+- `endpoint`: REST uses `http(s)://`; WebSocket uses `ws(s)://`.
+- `auth_type`: `none`, `bearer`, `api_key`, or `basic`.
+- `headers`: static request headers.
+- `auth_config`: token, API key, or basic username/password; API keys can be sent by header or query.
+- `config.target_schema`: for example `vessel_ais`.
+- `config.delivery_mode`: REST defaults to `polling`; WebSocket defaults to `realtime_stream`.
+- `config.merge_target_source`: records which built-in source this custom source supplements, such as `barentswatch_vessels`.
+
+The REST runner supports:
+
+- `GET` / `POST`
+- query params
+- JSON body
+- headers and auth injection
+- active mapping writes into the target schema
+
+The WebSocket runner supports:
+
+- endpoint format validation
+- headers and auth injection
+- optional `ws_subscribe_message`
+- `ws_message_path` / `ws_items_path` extraction
+- reconnects
+- `debug_max_messages` debug limits
+- background stream start / stop / status
+
+Related APIs:
+
+```http
+POST /api/v1/datasources/custom/sample
+GET  /api/v1/datasources/target-schemas
+POST /api/v1/datasources/{config_id}/run-mapped
+POST /api/v1/datasources/{config_id}/stop-mapped
+GET  /api/v1/datasources/{config_id}/mapped-status
+DELETE /api/v1/datasources/configs/{config_id}?delete_mappings=true&delete_source_data=true
+```
+
+`run-mapped?background=true` only matters for WebSocket sources and starts a background stream. REST sources remain one-shot collection runs.
+
+### Delete And Data Cleanup
+
+Deleting a custom source has three levels:
+
+- Delete configuration only: preserve mapping and historical data.
+- Delete configuration and mapping: also delete mapping templates for that config.
+- Delete configuration, mapping, and source data: delete that source's `collected_data`, `ais_raw_observations`, and `ais_source_health`.
+
+When deleted `vessel_ais` source data affects Earth, the backend broadcasts `reload_required` on the `vessels` channel so Earth reloads aggregated vessels. Legacy `vessel_position` rows are not deleted by custom source because that table cannot safely attribute rows back to a custom source.
+
+### Local AIS Mock WebSocket
+
+File:
+
+- [mock-ais-ws-server.ts](/home/ray/dev/linkong/planet/scripts/mock-ais-ws-server.ts)
+
+Run:
+
+```bash
+bun run mock:ais-ws
+```
+
+The mock service continuously sends AIS-like JSON to validate the chain: WebSocket custom source -> mapping -> AIS raw observation -> `vessels` channel -> Earth vessel upsert. Typical config:
+
+```json
+{
+  "source_type": "websocket",
+  "endpoint": "ws://localhost:8787",
+  "config": {
+    "target_schema": "vessel_ais",
+    "delivery_mode": "realtime_stream",
+    "merge_target_source": "barentswatch_vessels",
+    "ws_message_path": "$.data",
+    "ws_items_path": "$.vessels[*]",
+    "ws_reconnect": true
+  }
+}
+```
+
 ## Credential Guide

 File:
@@ -345,6 +441,7 @@ Added coverage:
 Credential providers currently supported:

 - `barentswatch`
+- `aisstream`
 - `spacetrack`

 Other collectors with `requires_credentials=true` return that their credential chain has not been wired yet, and the frontend shows `Unavailable`.
--- a/docs/technical/en/docs-gatekeeper-development.md
+++ b/docs/technical/en/docs-gatekeeper-development.md
@@ -0,0 +1,116 @@
+# Docs Gatekeeper Development Guide
+
+Docs Gatekeeper moves `/docs` from "bundle all Markdown into the frontend" to "return catalog and content from the backend according to permissions." Its goal is to keep public manuals, user docs, developer docs, and admin/ops docs in one searchable Docs page while making every protected Markdown body pass through a server-side whitelist and authorization check.
+
+For the user workflow, see the Docs section in [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md).
+
+## Authorization Model
+
+Docs uses two permission layers:
+
+- `users.role`: preserved for console/system permissions.
+- `users.gatekeeper_groups`: Docs content permission groups.
+
+Groups:
+
+| Group | Purpose |
+| --- | --- |
+| `docs_user` | User-operation docs |
+| `docs_developer` | Earth, frontend, backend, collector, and AI Provider development docs |
+| `docs_admin` | Service control, operations, environment, and sensitive-operation docs |
+
+Inheritance:
+
+- Anonymous users can only read `public`.
+- `docs_developer` includes `docs_user`.
+- `docs_admin` includes `docs_developer` and `docs_user`.
+- `admin` and `super_admin` receive all Docs permissions by default.
+
+## Backend Entry Points
+
+Files:
+
+- [docs.py](/home/ray/dev/linkong/planet/backend/app/api/v1/docs.py)
+- [docs_gatekeeper.py](/home/ray/dev/linkong/planet/backend/app/services/docs_gatekeeper.py)
+- [user.py](/home/ray/dev/linkong/planet/backend/app/models/user.py)
+- [users.py](/home/ray/dev/linkong/planet/backend/app/api/v1/users.py)
+
+APIs:
+
+```http
+GET /api/v1/docs/catalog
+GET /api/v1/docs/{lang}/{slug}
+```
+
+`catalog` returns only documents visible to the current user. The content endpoint validates language, slug, and file existence through the metadata whitelist before checking access:
+
+- Anonymous protected-doc request: `401`.
+- Authenticated but insufficient permissions: `403`.
+- Unknown language, unknown slug, or missing file: `404`.
+
+Markdown bodies can only come from whitelisted files under `docs/technical/{zh,en}/`; arbitrary path reads are not allowed.
+
+## Metadata Source
+
+Server-side metadata lives in [docs_gatekeeper.py](/home/ray/dev/linkong/planet/backend/app/services/docs_gatekeeper.py):
+
+```python
+DocsMetadata(
+    "manual.md",
+    "manual",
+    "public",
+    "Manual",
+    2,
+    "Planet 使用手册",
+    "Planet Manual",
+)
+```
+
+When adding a public technical doc:
+
+- Add both Chinese and English Markdown files.
+- Add filename, slug, access, group, order, and titles to server `DOCS_METADATA`.
+- Add matching metadata to frontend [docs-content.ts](/home/ray/dev/linkong/planet/frontend/src/pages/Docs/docs-content.ts) so navigation titles and sorting stay aligned.
+- Update `docs/technical/zh/README.md` and `docs/technical/en/README.md` when the document should be discoverable from the README.
+
+## User Management
+
+The `users` table has `gatekeeper_groups JSONB DEFAULT '[]'`. Startup [session.py](/home/ray/dev/linkong/planet/backend/app/db/session.py) applies `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` for existing local databases.
+
+The user API:
+
+- Writes `gatekeeper_groups` during user creation.
+- Validates group names on update: only `docs_user`, `docs_developer`, and `docs_admin` are accepted.
+- Allows only `super_admin` to modify Gatekeeper groups.
+
+Frontend [Users.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Users/Users.tsx) displays group tags and provides a multi-select in the edit form. Non-`super_admin` users see the field disabled, and submission removes `gatekeeper_groups` before sending.
+
+## Frontend Docs Loading
+
+Files:
+
+- [Docs.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Docs/Docs.tsx)
+- [docs-content.ts](/home/ray/dev/linkong/planet/frontend/src/pages/Docs/docs-content.ts)
+- [docs-search.ts](/home/ray/dev/linkong/planet/frontend/src/pages/Docs/docs-search.ts)
+
+Key changes:
+
+- Remove `import.meta.glob(...?raw)` as the Markdown content source.
+- Load `/api/v1/docs/catalog` to build the visible navigation.
+- Load `/api/v1/docs/{lang}/{slug}` for document bodies.
+- Index search only across currently visible docs, loading Markdown from the backend as needed.
+- Show login state for `401`, permission state for `403`, and unavailable-doc state for `404`.
+
+## Test Coverage
+
+Relevant tests:
+
+- [test_docs_gatekeeper.py](/home/ray/dev/linkong/planet/backend/tests/test_docs_gatekeeper.py)
+
+Tests should cover:
+
+- Anonymous users only see public docs.
+- Protected content returns `401` or `403` appropriately.
+- `docs_developer` can read developer docs but not admin docs.
+- `admin` and `super_admin` can read admin docs.
+- Unknown slugs, unknown languages, and path traversal strings cannot read files.
--- a/docs/technical/en/earth-frontend-context.md
+++ b/docs/technical/en/earth-frontend-context.md
@@ -99,7 +99,7 @@ Responsibilities:
 - [vessels.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/vessels.js)
 - [bgp.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp.js)
 - [bgp-cruise-adapter.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/bgp-cruise-adapter.js)
- [compute-centers.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/compute-centers.js)
+- [compute-centers.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/compute-centers.js) renders supercomputer and GPU-cluster markers. The backend renders compute centers only from source-provided coordinates or `compute_center_locations` dimension-table coordinates during startup; manual candidate collection can query ROR and Nominatim/OpenStreetMap, and the layer keeps the `?` badge for unconfirmed positions while the details card shows precision, confidence, source notes, and verification date.
 - [country-boundaries.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/country-boundaries.js)

 Each module is responsible for its own:
@@ -109,6 +109,8 @@ Each module is responsible for its own:
 - State tracking (loaded, visible, hover, locked)
 - Self-cleanup (dispose on scene destroy)

+The compute-center layer row has a notification badge for GeoJSON `unresolved` records. The badge means "no trustworthy coordinates, cannot render on the globe"; it is different from the `?` marker drawn on already positioned but unconfirmed compute centers. Clicking the badge opens a fixed info card beside the layer panel. Row-level `采集` fetches candidates only. Header-level `一键采用` processes the queue top-to-bottom, saves the highest-confidence valid candidate, removes successful rows, renumbers the list, and dispatches `earth:compute-center-unresolved-count-change` so the badge updates immediately. When the batch ends, `earth:compute-center-location-saved` refreshes the real layer.
+
 ### AIS Vessel Layer

 The vessel layer fetches `/api/v1/visualization/geo/vessels` and renders the aggregated AIS GeoJSON through `createInteractableLayer()`. By default it does not send a `limit` parameter, and `VESSEL_CONFIG.maxRenderedMarkers = 0` means the frontend does not clip the result to 5000 vessels. A positive `options.limit` or positive `maxRenderedMarkers` can still be used as an explicit temporary cap.
@@ -154,6 +156,8 @@ Layer toggle buttons use `data-status-target` attributes to link button state to

 This is the canonical way to synchronize button visual state with actual layer state. Do not maintain separate boolean flags for button display.

+Terrain should not block startup when it is not the restored visible layer. After deferred layer visibility settings are applied, `controls.js` schedules `scheduleTerrainPrefetch()` only when HD texture is enabled, terrain is not ready, and no prefetch is already running. The prefetch uses `setTimeout` plus `requestIdleCallback` so cloud, HD texture, and startup layer work keep first-screen priority.
+
 ## Current Settings Persistence

 Earth settings are stored in `localStorage`. The key is typically a namespaced string defined in `constants.js`. `controls.js` handles read, write, and reset.
@@ -171,6 +175,8 @@ Settings that affect visual layers (terrain opacity, day/night mode, satellite d

 When HD texture is off, terrain is temporarily hidden and its state is remembered. When HD texture comes back on, terrain restores its prior visibility.

+Terrain tile fetching is batched. `terrain.js` deduplicates required Terrarium tile keys and sends chunks sized by `TERRAIN_CONFIG.batchRequestSize` to `/api/v1/visualization/terrain/terrarium/batch`. The backend proxies S3 Terrarium tiles with an in-memory LRU cache, per-batch deduplication, and bounded concurrency. The single tile endpoint remains for fallback paths and browser cache semantics.
+
 ## Current High-Frequency Risk Points

 ### 1. Visual State and Business State Out of Sync
--- a/docs/technical/en/earth-toolbar-overlay-coordination.md
+++ b/docs/technical/en/earth-toolbar-overlay-coordination.md
@@ -0,0 +1,86 @@
+# Earth Toolbar And Overlay Coordination
+
+This document describes the current coordination rules between the Earth toolbar buttons and the search panel, settings modal, news/live panel, and layer panel. Use this matrix when changing interactions, adding buttons, or adjusting panels so one action does not close an unrelated overlay.
+
+Related entries:
+
+- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
+- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
+
+## Toolbar Button Directory
+
+The toolbar is marked by `.earth-toolbar-btn` in [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html):
+
+| ID | Title | Type | Overlay / action |
+|----|-------|------|------------------|
+| `layer-action` | Layers | Overlay toggle | HUD panel `layer-toggles` on desktop / mobile drawer `layers` card |
+| `search-action` | Search | Overlay toggle | Search panel on desktop / mobile drawer `search` card |
+| `rotate-toggle` | Auto rotate | Standalone toggle | No overlay |
+| `toggle-tv` | News live | Overlay toggle | Media panel `media-panel` with TV and News tabs |
+| `reload-data` | Reload data | Standalone action | No overlay |
+| `zoom-trigger` | Zoom control | Floating menu | Zoom floating menu |
+| `settings-trigger` | Settings | Overlay toggle | Settings modal on desktop / mobile drawer `settings` card |
+| `reset-view` | Reset view | Standalone action | No overlay |
+| `layout-toggle` | Maximize layout | Standalone toggle | No overlay |
+
+## Shared Coordination Entry Point
+
+[controls.js::closeTransientMobileOverlays](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js) is the shared coordinator for deciding what should close when an overlay opens.
+
+Every path that opens a fullscreen-style overlay calls `closeTransientMobileOverlays({ except })`, where `except` names the overlay that should stay open:
+
+```js
+closeTransientMobileOverlays({ except: "search" });
+closeTransientMobileOverlays({ except: "settings" });
+closeTransientMobileOverlays({ except: "media" });
+closeTransientMobileOverlays({ except: "layer-toggles" });
+```
+
+Current `except` values are `"search"`, `"settings"`, `"media"`, `"layer-toggles"`, or omitted to close all transient overlays.
+
+## Close Matrix
+
+`close` means the overlay closes; `keep` means it remains open.
+
+| Action | Search | Settings | Mobile layers drawer | News/live |
+|--------|:------:|:--------:|:--------------------:|:---------:|
+| Open search (`except: "search"`) | self | close | close | keep |
+| Open settings (`except: "settings"`) | close | self | close | keep |
+| Open news/live (`except: "media"`) | close | close | close | self |
+| Open mobile layers (`except: "layer-toggles"`) | close | close | self | close |
+| Close all (`except: null`) | close | close | close | close |
+
+Examples:
+
+- Clicking toolbar Settings closes search and the mobile layer drawer, but keeps news/live open.
+- Clicking toolbar Layers on mobile opens the `layers` drawer and closes search, settings, and news.
+- Clicking News Live closes search, settings, and the layer drawer, then toggles the media panel.
+
+## Design Rules
+
+1. **Floating menus such as `zoom-trigger` are not overlays.** They use `bindFloatingMenu` and are managed separately by `closeFloatingMenus()`. Opening any overlay first closes floating menus.
+2. **Desktop `layer-toggles` is a persistent HUD panel.** `closeTransientMobileOverlays` only closes it when `activeMobileDrawerId === "layer-toggles"`, so desktop search, settings, and news do not disturb the layer panel.
+3. **News/live is independent from settings.** Users often adjust collector settings while watching news, so opening settings does not close the media panel. This became an invariant after the May 2026 coordination patch.
+4. **Search and news are both primary information overlays.** Search opens without closing news, and news opens without closing search. If product direction changes, update both sides in `closeTransientMobileOverlays` so the matrix stays symmetric.
+5. **Mobile drawers are fullscreen-focus states.** Any mobile drawer, whether layers, search, or settings, uses `setMobileDrawerState` and closes other overlays.
+6. **Escape has a fixed close order.** See [controls.js::setupKeyboardControls](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js): search, settings, mobile drawer, floating menu, toolbar hub, locked object.
+
+## Adding A Button Or Overlay
+
+1. Add the button in the `.earth-toolbar` container in [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html), using the existing `floating-btn liquid-glass-surface earth-toolbar-btn` class pattern.
+2. Decide whether it is a standalone action, a floating menu, or a mutually coordinated overlay.
+3. For a coordinated overlay, call `closeTransientMobileOverlays({ except: "<your-key>" })` when opening it.
+4. Add the reciprocal close branch inside `closeTransientMobileOverlays`, so other overlays can close yours.
+5. If the new overlay should coexist with an existing overlay, exclude that peer on both sides of the matrix.
+6. Add an Escape close path in `setupKeyboardControls`.
+7. On mobile, use `setMobileDrawerState({ open: true, card: "<your-card>" })` for drawer-style panels.
+
+## Current Implementation Locations
+
+- Coordinator: [controls.js::closeTransientMobileOverlays](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
+- Settings overlay: [controls.js::openSettingsModal / closeSettingsModal](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
+- Search overlay: [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js), imported from the search module
+- News/live overlay: [tv.js::setTVPanelVisible](/home/ray/dev/linkong/planet/frontend/public/earth/js/tv.js), with the News tab in [news.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/news.js)
+- Mobile layer drawer: [controls.js::setMobileDrawerState](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
+- Floating menu: [controls.js::bindFloatingMenu](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
+- Toolbar DOM: [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html)
--- a/docs/technical/en/frontend-admin-frontend-context.md
+++ b/docs/technical/en/frontend-admin-frontend-context.md
@@ -155,6 +155,7 @@ Purpose:
 - Renders Markdown content for `/docs`
 - Supports headings, lists, blockquotes, code blocks, tables, and basic inline formatting
 - Code blocks and tables reuse `Scrollbar` so horizontal content does not blow out the docs page
+- Docs content is returned by backend `/api/v1/docs/...` endpoints according to Gatekeeper permissions; the frontend only renders content visible to the current user

 Current constraints:

@@ -190,9 +191,10 @@ Responsibilities:

 - Token
 - Current user
+- Gatekeeper groups
 - Login / logout

-`App.tsx` uses it to decide whether to redirect to the login page.
+`App.tsx` uses it to decide whether to redirect to the login page. `/docs` remains a public route, but the backend decides the visible catalog and content from the token; anonymous visitors only receive public docs.

 ### 2. Business Data Gateway

--- a/docs/technical/en/location-pipeline-development.md
+++ b/docs/technical/en/location-pipeline-development.md
@@ -0,0 +1,200 @@
+# Shared Location Resolution Pipeline Development Guide
+
+`backend/app/services/location/` is the shared abstraction for any "given a record, decide its lat/lon" workflow. Compute centers, BGP collectors, and BGP events now run on this pipeline. Future entities such as satellite ground stations, user-claimed points, and IXP facilities should plug in here instead of creating another geocoding path.
+
+For the user workflow, see [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md).
+
+## Design Goals
+
+Historically compute centers had their own four-tier chain, BGP collectors used a hard-coded dictionary, and BGP events inherited collector coordinates. These implementations did not share code, and new algorithms had no stable insertion point.
+
+The refactored rules:
+
+- Share the `LocationResolver` protocol and `LocationPipeline` orchestrator.
+- Domain modules only build `LocationQuery` and choose resolver order.
+- New algorithms join by adding resolver classes, without changing ingestion, API, or frontend envelopes.
+- Earth renders only city-level or better locations.
+- Local JSON registries are not runtime candidate sources for compute centers or BGP collectors; persisted location facts live in database dimension tables.
+
+## Core Interfaces
+
+```python
+@dataclass(frozen=True)
+class LocationQuery:
+    name: str | None
+    aliases: tuple[str, ...]
+    city: str | None
+    country: str | None
+    region: str | None
+    source_latitude: float | None
+    source_longitude: float | None
+    extra: Mapping[str, Any]
+```
+
+```python
+@dataclass(frozen=True)
+class LocationCandidate:
+    latitude: float
+    longitude: float
+    display_name: str
+    precision: str
+    confidence: float
+    source: str
+    needs_confirmation: bool
+    matched_fields: tuple[str, ...]
+    suggested_registry_entry: dict | None
+```
+
+```python
+class LocationResolver(Protocol):
+    name: str
+    def resolve(self, query: LocationQuery) -> ResolverOutput: ...
+```
+
+`LocationPipeline.collect_candidates()` returns sorted candidates plus `attempted_queries`; `resolve_best()` returns the best candidate with diagnostics. The default sort key ranks source, precision, and confidence, then deduplicates candidates with the same source and rounded coordinates.
+
+## Built-In Resolvers
+
+| Resolver | File | Responsibility |
+| --- | --- | --- |
+| `SourceCoordinatesResolver` | `resolvers/source_coordinates.py` | Emits `precision="precise"` when the record already has lat/lon |
+| `RegistryResolver` | `resolvers/registry.py` | Legacy generic resolver; current compute-center and BGP runtime paths do not use it to generate candidates |
+| `NominatimResolver` | `resolvers/nominatim.py` | Runs a domain query plan against Nominatim with LRU cache and rate limiting |
+| `InheritFromAnotherEntityResolver` | `resolvers/inherit.py` | Wraps an externally resolved entity location as a candidate |
+
+`RegistryResolver` remains available for future controlled import scenarios, but it should not be reconnected as a hard-coded hint source for compute centers or BGP. Matching common fields such as `operator` or `city` was the main reason multiple entities could collapse onto the same point.
+
+## Current Domain Pipelines
+
+### Compute Centers
+
+Entry points:
+
+- [compute_center_locations.py](/home/ray/dev/linkong/planet/backend/app/services/compute_center_locations.py)
+
+Resolver order:
+
+```python
+SourceCoordinatesResolver()
+StoredComputeCenterLocationResolver()
+```
+
+The main map startup path is source coordinates first, then the database-backed current-location table. The table is `compute_center_locations`, keyed by `(source, source_id)`, and stores manually accepted locations or true coordinates migrated from source records. `init_db()` only migrates source records that already contain real coordinates; it does not import old hard-coded hints and does not run ROR, Nominatim, or LLM geocoding during startup.
+
+Candidate collection is intentionally separate from rendering. `collect_location_candidates()` builds ROR and Nominatim/OpenStreetMap queries from source fields, but it does not emit the current `compute_center_locations` row as a candidate. After a user accepts a candidate, the save endpoint upserts it into the dimension table; the next map refresh renders it through `StoredComputeCenterLocationResolver`.
+
+`resolve_compute_center_location()`, `resolve_compute_center_location_full()`, and `collect_location_candidates()` remain the domain API. `visualization.py` consumes that API and no longer owns coordinate hints, country-centroid fallbacks, or Nominatim details.
+
+GeoJSON output includes only `RENDERABLE_PRECISIONS`. Unresolved records are returned in `unresolved` with `failure_reason`, `attempted_queries`, `source_id`, `record_id`, and related diagnostics.
+
+### BGP Collectors
+
+Entry points:
+
+- [bgp_collector_locations.py](/home/ray/dev/linkong/planet/backend/app/services/bgp_collector_locations.py)
+- [bgp_collector_location.py](/home/ray/dev/linkong/planet/backend/app/models/bgp_collector_location.py)
+
+Resolver order:
+
+```python
+SourceCoordinatesResolver()
+StoredCollectorLocationResolver()
+NominatimResolver(_bgp_collector_query_plan)
+```
+
+The 23 RIPE RIS collector coordinates moved from the old table into the `bgp_collector_locations` dimension table with `source=legacy_seed` and `needs_confirmation=true`. The legacy dictionary is still maintained from the DB-backed cache for compatibility; manual candidate collection uses stored site/city/country as context but does not emit stored rows as candidates.
+
+### BGP Events
+
+Entry point:
+
+- [bgp_event_locations.py](/home/ray/dev/linkong/planet/backend/app/services/bgp_event_locations.py)
+
+Resolver order:
+
+```python
+SourceCoordinatesResolver()
+InheritFromAnotherEntityResolver(_inherit_from_owning_collector)
+```
+
+Event inheritance uses a strict owning-collector lookup and does not run the full fuzzy collector registry. Future ASN facility, PrefixGeo, or PeeringDB resolvers can be inserted after inheritance.
+
+## API Envelope
+
+```http
+POST /api/v1/visualization/compute-centers/{source_id}/collect-location
+POST /api/v1/visualization/compute-centers/{source_id}/location
+POST /api/v1/bgp/collectors/{collector_id}/collect-location
+```
+
+Both `collect-location` endpoints return the same envelope:
+
+```json
+{
+  "success": true,
+  "candidates": [],
+  "best_candidate": {},
+  "attempted_queries": [],
+  "context": {}
+}
+```
+
+`POST /api/v1/visualization/compute-centers/{source_id}/location` upserts the candidate selected by the frontend into `compute_center_locations`. Manual saves default to `needs_confirmation=false`, `verification_status="verified"`, and a `verified_at` timestamp. Future automated staging can pass `needs_confirmation=true` explicitly.
+
+The frontend [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) renders the shared candidate list and preview events. The compute-center layer button shows an `unresolved` badge; clicking it opens the unresolved queue. Row-level `采集` only fetches candidates. Header-level `一键采用` walks the queue top-to-bottom, picks the highest-confidence candidate with valid coordinates, saves it, removes the row, renumbers the list, and dispatches `earth:compute-center-unresolved-count-change` so the badge updates immediately. When the batch finishes, `earth:compute-center-location-saved` refreshes the real layer.
+
+If the remaining records have no city-level candidates, the batch must not invent coordinates. The UI keeps those rows and shows the backend `failure_reason` plus attempted queries.
+
+## Adding A Resolver
+
+A resolver only needs `name` and `resolve()`, returning `ResolverOutput`.
+
+```python
+class PeeringDBFacilityResolver:
+    name = "peeringdb_facility"
+
+    def __init__(self, client):
+        self._client = client
+
+    def resolve(self, query):
+        asn = query.extra.get("origin_asn")
+        if not asn:
+            return ResolverOutput()
+        return ResolverOutput(candidates=tuple(
+            LocationCandidate(
+                latitude=f.latitude,
+                longitude=f.longitude,
+                display_name=f.name,
+                precision="site",
+                confidence=0.78,
+                query=f"peeringdb::{asn}",
+                source=self.name,
+                source_note=f"PeeringDB facility for AS{asn}",
+                matched_fields=("origin_asn",),
+                needs_confirmation=False,
+                city=f.city,
+                country=f.country,
+            )
+            for f in self._client.facilities_for_asn(asn)
+        ))
+```
+
+Wire it in:
+
+```python
+BGP_EVENT_PIPELINE = LocationPipeline([
+    SourceCoordinatesResolver(),
+    InheritFromAnotherEntityResolver(source_lookup=...),
+    PeeringDBFacilityResolver(client=peeringdb_client),
+])
+```
+
+## Test Coverage
+
+Relevant tests:
+
+- [test_location_pipeline.py](/home/ray/dev/linkong/planet/backend/tests/test_location_pipeline.py)
+- [test_bgp_collector_locations.py](/home/ray/dev/linkong/planet/backend/tests/test_bgp_collector_locations.py)
+- [test_visualization_compute_centers.py](/home/ray/dev/linkong/planet/backend/tests/test_visualization_compute_centers.py)
+
+Coverage focuses on resolver pluggability, registry alias guards, BGP collector legacy dictionary compatibility, compute-center public API compatibility, and non-renderable locations being returned as `unresolved`.
--- a/docs/technical/en/location-pipeline-user.md
+++ b/docs/technical/en/location-pipeline-user.md
@@ -0,0 +1,127 @@
+# Earth Location Candidate Collection User Guide
+
+Location candidate collection helps fill or verify coordinates for compute centers and BGP collectors on Earth. Users do not type coordinates by hand; the backend ranks source coordinates, open organization-registry results, and online geocoding results into a previewable candidate list.
+
+## Supported Entities
+
+Currently supported:
+
+- Compute centers: TOP500 supercomputers and Epoch AI GPU clusters.
+- BGP collectors: RIPE RIS `rrcXX` collectors.
+
+BGP events inherit the location of their owning collector. Events do not have a separate collection button yet; future ASN facility, prefix geography, or PeeringDB resolvers should use the same pipeline.
+
+## What Users See
+
+Clicking a compute center or BGP collector on Earth opens a detail card with location fields:
+
+| Field | Meaning |
+| --- | --- |
+| Location precision | Precise coordinates, site-level, city-level, or unconfirmed |
+| Location source | Source coordinates, ROR organization registry, Nominatim online search, or stored BGP collector locations |
+| Location confidence | Relative confidence reported by the backend resolver |
+| Verification status | Confirmed, estimated, or online result pending confirmation |
+| Resolution reason | Why the location was selected |
+| Matched location name | Canonical name from an open source, online result, or stored collector location |
+| Verified at | Verification date for confirmed locations; online candidates are usually empty |
+
+Compute-center GeoJSON no longer renders country centroids, unknown locations, or `[0, 0]` placeholders. Records that cannot reach city-level precision are returned in the endpoint's `unresolved` list and can be improved through candidate collection.
+
+A compute center with a `?` marker on Earth is not unresolved. It already has coordinates, but the coordinates still need confirmation, either because `needs_confirmation=true` or because the source is online geocoding. Truly unresolved records have no trustworthy coordinates and are therefore absent from the globe.
+
+## Collect Candidates
+
+1. Open `http://localhost:3000/earth`.
+2. Enable the `Compute centers` or `BGP observation` layer.
+3. Click an object to open its detail card.
+4. Click `自动采集坐标候选` or `重新自动采集坐标`.
+5. Wait for up to five candidates to appear.
+6. Click `预览` on a candidate row; Earth flies to that latitude and longitude.
+
+Candidate rows show:
+
+- Candidate name.
+- Precision: precise, site, or city.
+- Resolver source.
+- Confidence.
+- Coordinates.
+
+Clicking `保存` on a candidate row writes the selected compute-center candidate into the location dimension table. After the save succeeds, the compute-center layer refreshes; if the record was previously in the unresolved queue, the unresolved count decreases.
+
+## Unresolved Queue And Adopt All
+
+The notification badge on the compute-center layer row shows the current unresolved count. Clicking it opens a fixed queue beside the layer panel:
+
+1. The queue contains only compute centers without trustworthy coordinates.
+2. Row-level `采集` calls the candidate endpoint and shows up to five previewable candidates.
+3. Header-level `一键采用` walks the list from top to bottom, chooses the highest-confidence candidate with valid coordinates, and saves it.
+4. Each successful save immediately removes that row, renumbers the remaining rows, and updates the badge count.
+5. When the batch completes, the frontend refreshes the compute-center layer so UI state and backend state converge.
+
+If a record has no saveable candidate, the system does not invent a country centroid, vendor headquarters, or hard-coded hint. The row stays in the queue with the backend failure reason and attempted queries so an operator can supply better evidence later.
+
+## Backend APIs
+
+The frontend buttons call:
+
+```http
+POST /api/v1/visualization/compute-centers/{source_id}/collect-location
+POST /api/v1/visualization/compute-centers/{source_id}/location
+POST /api/v1/bgp/collectors/{collector_id}/collect-location
+```
+
+Both `collect-location` endpoints use the same response shape:
+
+```json
+{
+  "success": true,
+  "candidates": [],
+  "best_candidate": {},
+  "attempted_queries": [],
+  "context": {}
+}
+```
+
+When no candidate reaches city-level precision, `success` is `false` and the response includes `failure_reason` plus the attempted queries. This helps distinguish missing source fields, open-source gaps, and online geocoding misses.
+
+## Registry Maintenance
+
+Compute centers and BGP collectors no longer maintain local candidate registries. Compute-center accepted locations are stored in the `compute_center_locations` database dimension table keyed by `(source, source_id)`. BGP collector current locations are stored in the `bgp_collector_locations` database dimension table; the old RIPE RIS city-level coordinates are used only as initialization seed data and still require confirmation.
+
+For compute centers, prefer maintaining:
+
+- `source` / `source_id`: for example `top500` + `top500_50`.
+- `name` / `operator` / `site`.
+- `city` / `country`.
+- `latitude` / `longitude`.
+- `precision`: `precise`, `site`, or `city`.
+- `confidence`: confidence from 0 to 1.
+- `location_source` / `source_url` / `source_note` / `raw_payload`: evidence source.
+- `needs_confirmation` / `verification_status` / `verified_at`: manual verification status and date.
+
+For BGP collectors, prefer maintaining:
+
+- `collector_id`: for example `rrc12`.
+- `site` / `operator`: site and operator.
+- `city` / `country` / `region`.
+- `latitude` / `longitude`.
+- `precision`: `precise`, `site`, or `city`.
+- `confidence`: confidence from 0 to 1.
+- `source` / `source_url` / `raw_payload`: evidence source.
+- `verification_status` / `verified_at`: manual verification status and date.
+
+If only the city is known, use city-level precision. Do not enter a precise-looking coordinate that has not been verified.
+
+## Common Questions
+
+### Why are some compute centers missing on Earth?
+
+Earth only renders coordinates that reach city-level precision or better. If source data, verified storage, and online geocoding all fail, the record is returned as `unresolved` instead of being rendered at a misleading country center or `[0, 0]`.
+
+### Why do online results need confirmation?
+
+Nominatim/OpenStreetMap results may match same-name cities, organizations, or campuses. They are useful for previewing candidates, but should be manually confirmed before being persisted as verified locations.
+
+### Why do BGP events no longer all land in Amsterdam?
+
+The old behavior could match common fields like `operator="RIPE NCC"` and incorrectly promote `rrc00`. BGP event inheritance now uses a strict owning-collector lookup in the DB-backed cache instead of registry fuzzy matching.
--- a/docs/technical/en/manual.md
+++ b/docs/technical/en/manual.md
@@ -5,7 +5,7 @@ This manual is for daily use, demos, development integration, and local operatio
 - `planet.sh`: local start, stop, restart, health check, and log access
 - Earth: public 3D situational awareness page
 - Console: admin backend (login required)
- Docs: public developer documentation and manual
+- Docs: backend Gatekeeper-controlled documentation; basic usage docs are public, while developer and operations docs require permission groups

 For the shortest path to getting started, see [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md).

@@ -16,7 +16,7 @@ After a default startup, the common URLs are:
 | Name | URL | Login Required | Description |
 | --- | --- | --- | --- |
 | Earth | `http://localhost:3000/earth` | No | 3D globe, layers, BGP, satellites, cables, news situational awareness |
-| Docs | `http://localhost:3000/docs` | No | Developer docs, technical reference, usage manual |
+| Docs | `http://localhost:3000/docs` | Partly | Usage docs are public; developer, backend, and operations docs require Gatekeeper groups |
 | Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
 | AI Playground | `http://localhost:3000/playground` | Yes | AI Provider status and debugging |
 | Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |
@@ -176,7 +176,26 @@ Useful for:
 - Demos on phone or tablet
 - Another machine on the same LAN accessing the same dev instance

-After starting, check your firewall and WSL network forwarding if access fails.
+`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but access from a phone or another computer through `http://<Windows LAN IP>:3000` still depends on Windows port forwarding and firewall rules.
+
+Use this order to diagnose:
+
+```bash
+# From WSL or the shell running Planet
+curl http://localhost:3000
+curl http://localhost:8000/health
+ss -ltnp | grep -E ':3000|:8000'
+```
+
+If this shows `0.0.0.0:3000` and `0.0.0.0:8000`, but the LAN IP still fails, configure Windows from an elevated PowerShell:
+
+```powershell
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
+
+New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
+New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
+```

 ## Earth

@@ -259,6 +278,12 @@ Earth search finds current globe objects, such as:

 Search results can be used to quickly locate objects and open their details.

+### Location Candidate Collection
+
+Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use `自动采集坐标候选` or `重新自动采集坐标`; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. Stored BGP collector locations are used as query context only and are not emitted as candidates.
+
+Candidates can be previewed directly on Earth. Compute-center candidates can be saved into the `compute_center_locations` dimension table from the detail card, then the layer refreshes immediately. The notification badge on the compute-center layer row shows unresolved records that cannot be rendered; clicking it opens the queue, where users can collect individual candidates or use `一键采用` to save the highest-confidence candidate top-to-bottom. Records without candidates stay in the queue and are not replaced by country centroids or hard-coded hints. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md) for the full workflow.
+
 ### Settings

 The settings panel contains:
@@ -492,33 +517,41 @@ Then open `/logs` for more structured runtime information.

 ## Docs

-Public documentation site:
+Documentation site:

 ```text
 http://localhost:3000/docs
 ```

-Current public content comes from:
+Docs content is read through backend APIs by permission. The frontend no longer bundles all Markdown files directly. Source files still live in:

 ```text
 docs/technical/zh/   (Chinese)
 docs/technical/en/   (English)
 ```

+Anonymous visitors only see `public` docs such as the overview, quickstart, and manual. Logged-in users can see more technical docs when assigned Gatekeeper groups:
+
+- `docs_user`: user-operation docs.
+- `docs_developer`: Earth, frontend, backend, collector, and AI Provider development docs.
+- `docs_admin`: service control, operations, environment variable, and sensitive-operation docs.
+
+`admin` receives admin-doc access by default, and `super_admin` can read all Docs content. Gatekeeper groups are configured in the console Users page.
+
 Docs supports:

 - Category navigation
 - Markdown rendering
 - Tables and code blocks
 - In-document table of contents
- Local search
+- Search across currently visible docs
 - Internal links between technical documents

 When adding a new technical document, check:

 - Does it have a clear top-level heading
- Does it need to be added to the `/docs` manual category and ordering
- Does it contain information that should not be publicly displayed
+- Does it need to be added to backend Docs metadata for category and ordering
+- Should it be classified as `public`, `docs_user`, `docs_developer`, or `docs_admin`

 ## Development Command Conventions

@@ -589,5 +622,6 @@ When something goes wrong, follow this sequence:
 - [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
 - [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
 - [Earth Layer Style Reference](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
+- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
 - [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
 - [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
--- a/docs/technical/en/ops-planet-sh-startup.md
+++ b/docs/technical/en/ops-planet-sh-startup.md
@@ -0,0 +1,205 @@
+# `planet.sh` Startup Performance Optimization
+
+## Background
+
+`planet.sh` manages start, stop, restart, health checks, and logs for all local services. The previous implementation had several startup issues:
+
+1. AI Provider rebuilt every time, even when code had not changed.
+2. Port cleanup could wait up to 45 seconds.
+3. Port bind detection used a Python subprocess, adding about 300 ms per call.
+4. Plain `restart` and `restart -b` behaved differently.
+
+## Issue 1: AI Provider Rebuilt Every Time
+
+### Root Cause
+
+The build stamp file lived under `/tmp/`. After WSL or Linux restart, `/tmp` is cleared, so the `stamp_non_empty` condition failed and the script decided to rebuild:
+
+```bash
+# All three conditions had to be true to skip rebuild
+image_exists AND stamp_non_empty AND fingerprint_match
+```
+
+### Fix
+
+The stamp file moved to a persistent cache path:
+
+```bash
+AI_PROVIDER_BUILD_STAMP_FILE="$HOME/.cache/planet/aiprovider_build.sha256"
+```
+
+Writing the stamp creates the directory first:
+
+```bash
+write_ai_provider_build_stamp() {
+    mkdir -p "$(dirname "$AI_PROVIDER_BUILD_STAMP_FILE")"
+    compute_ai_provider_build_fingerprint > "$AI_PROVIDER_BUILD_STAMP_FILE"
+}
+```
+
+### Faster Fingerprint
+
+The previous implementation tarred the whole `aiprovider/` directory before hashing, which could take seconds in large trees. The new version uses `find + stat` and reads only file metadata:
+
+```bash
+compute_ai_provider_build_fingerprint() {
+    find aiprovider \
+        -type f \
+        ! -path '*/__pycache__/*' \
+        ! -name '.env' \
+        ! -name '.env.*' \
+        ! -name '*.pyc' \
+        ! -name '*.pyo' \
+        | LC_ALL=C sort \
+        | xargs -r stat --format="%Y %s %n" 2>/dev/null
+    sha256sum docker-compose.yml docker-compose.simple.yml 2>/dev/null
+    python3 "$SCRIPT_DIR/scripts/compute_aiprovider_dependency_fingerprint.py" 2>/dev/null
+}
+```
+
+This is roughly 10 times faster for many-small-file workloads while preserving the same practical rebuild signal. `.env` and `.env.*` are excluded because runtime model, key, and Base URL changes should not force an image rebuild.
+
+### Docker Build Context
+
+AI Provider only needs root `pyproject.toml`, `uv.lock`, and `aiprovider/` source code. Sending the entire repository as Docker build context wastes time on frontend assets, PDFs, historical data, and Unreal files.
+
+The root `.dockerignore` now narrows the context:
+
+```dockerignore
+**
+
+!pyproject.toml
+!uv.lock
+!aiprovider/
+!aiprovider/**
+
+aiprovider/.env
+aiprovider/.env.*
+!aiprovider/.env.example
+```
+
+The Dockerfile copies only AI Provider inputs:
+
+```dockerfile
+COPY pyproject.toml uv.lock /app/
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+COPY aiprovider /app/aiprovider
+```
+
+`uv sync` uses a BuildKit cache mount. The first build may still depend on network speed, but later builds reuse `/root/.cache/uv`.
+
+### Runtime Configuration
+
+Before starting AI Provider, `planet.sh` generates a temporary env-file and passes it to Compose or the manual `docker run` fallback. Configuration priority:
+
+1. `aiprovider/.env`
+2. simple `export AI_...=...` or `AI_...=...` lines from `~/.zshrc`
+
+The default parser is static and only covers AI Provider, image, and proxy variables. It avoids executing interactive shell initialization. Complex shell expansion can be enabled explicitly:
+
+```bash
+PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
+```
+
+To ignore personal shell config during debugging:
+
+```bash
+PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
+```
+
+### Skip-Rebuild Behavior
+
+When the fingerprint matches, the script skips `docker compose build` and starts the existing container:
+
+```bash
+docker start planet_aiprovider
+```
+
+`docker stop` stops the container without deleting the image. `cleanup_exit_containers` removes exited containers but not images, so the next `docker start` can reuse the existing image.
+
+## Issue 2: Slow Port Cleanup
+
+### Cause
+
+`wait_for_port_release` could wait up to 45 seconds by default: 15 attempts times 3 seconds.
+
+### Fix
+
+Background process cleanup now uses a 3-second timeout: TERM, 1.5 seconds, KILL, 1.5 seconds.
+
+```bash
+PORT_RELEASE_ATTEMPTS=15
+PORT_RELEASE_INTERVAL=0.2
+
+wait_for_port_release "$port" 15 0.2
+```
+
+`wait_for_port_release` accepts optional parameters so different situations can choose different timeouts.
+
+## Issue 3: Port Detection Used Python
+
+### Cause
+
+`can_bind_port` used `python3 -c "import socket..."`; each call cost about 300 ms.
+
+### Fix
+
+Prefer system tools and keep Python as a fallback:
+
+```bash
+can_bind_port() {
+    local port="$1"
+    if command -v ss >/dev/null 2>&1; then
+        ! ss -tlnH 2>/dev/null | awk '{print $4}' | grep -qE ":${port}$"
+        return
+    fi
+    if command -v lsof >/dev/null 2>&1; then
+        [ -z "$(lsof -tiTCP:"${port}" -sTCP:LISTEN 2>/dev/null)" ]
+        return
+    fi
+    python3 - "$port" <<'PY'
+import sys, socket
+p = int(sys.argv[1])
+s = socket.socket()
+s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+try:
+    s.bind(("", p)); s.close(); sys.exit(0)
+except OSError:
+    sys.exit(1)
+PY
+}
+```
+
+Frontend startup now has an additional pre-start cleanup retry layer:
+
+- `PORT_PRESTART_RETRIES`: defaults to 3 attempts.
+- `PORT_PRESTART_RETRY_INTERVAL`: defaults to 2 seconds.
+
+`kill_port_if_requested()` only kills processes when the current environment can identify listening PIDs. If no PID is visible but the port still cannot bind, it logs diagnostics and lets the service startup flow make the final decision. `start_frontend_with_retry()` only enters the pre-cleanup retry path when a listener PID is visible, so the script no longer spends its retry budget repeatedly killing nothing while a host-side or external network namespace is still releasing the port. Seeing "no listener found but port still unavailable" on the first restart usually means the external environment is still releasing the port, not that a local process cleanup loop is useful.
+
+## Issue 4: `restart` Behavior
+
+Before the stamp path fix:
+
+- `restart -b`: stop all services, check fingerprint, rebuild only when needed, then start.
+- plain `restart`: stop all services, then often rebuild AI Provider because `/tmp` lost the stamp.
+
+After moving the stamp file, plain `restart` uses the same `stop + start` behavior and the same fingerprint check as `restart -b`.
+
+## Other Cleanup
+
+Two redundant `sleep 3` waits were removed because health checks already cover the same readiness:
+
+- `start_backend_service`: post-database-health-check sleep.
+- `restart_database_service`: post-restart sleep.
+
+## Related Files
+
+- [planet.sh](/home/ray/dev/linkong/planet/planet.sh)
+- [.dockerignore](/home/ray/dev/linkong/planet/.dockerignore)
+- [aiprovider/Dockerfile](/home/ray/dev/linkong/planet/aiprovider/Dockerfile)
+- [docker-compose.yml](/home/ray/dev/linkong/planet/docker-compose.yml)
+- [docker-compose.simple.yml](/home/ray/dev/linkong/planet/docker-compose.simple.yml)
+- [compute_aiprovider_dependency_fingerprint.py](/home/ray/dev/linkong/planet/scripts/compute_aiprovider_dependency_fingerprint.py)
--- a/docs/technical/en/quickstart.md
+++ b/docs/technical/en/quickstart.md
@@ -30,6 +30,16 @@ Personal AI Provider configuration can also live in `~/.zshrc`. `planet.sh` read
 ./planet.sh restart -a
 ```

+Collector credentials such as AISStream and BarentsWatch can also start in `~/.zshrc` for connectivity validation:
+
+```bash
+export AISSTREAM_API_KEY="..."
+export BARENTSWATCH_CLIENT_ID="..."
+export BARENTSWATCH_CLIENT_SECRET="..."
+```
+
+For actual collection, prefer saving credentials in `Settings -> Collector Settings`, especially for AISStream's long-lived WebSocket collector. That keeps connectivity validation, backend collection tasks, and Earth realtime vessel aggregation on the same configuration source.
+
 ## 1. Start Services

 From the repository root:
@@ -44,7 +54,7 @@ After startup, the key URLs are:
 | --- | --- | --- |
 | Earth | `http://localhost:3000/earth` | Public 3D Earth visualization |
 | Console | `http://localhost:3000/admin` | Admin console (login required) |
-| Docs | `http://localhost:3000/docs` | Public developer docs and manual |
+| Docs | `http://localhost:3000/docs` | Usage docs are public; developer and operations docs require Gatekeeper groups |
 | AI Playground | `http://localhost:3000/playground` | AI debugging (login required) |
 | Backend API Docs | `http://localhost:8000/docs` | FastAPI / OpenAPI interface docs |

@@ -64,6 +74,8 @@ The console requires login. For first-time use:

 Follow the prompts to enter username, password, and role.

+To read developer or operations docs, log in as `super_admin` and assign Gatekeeper groups from the Users page. Use `docs_developer` for development docs and `docs_admin` for service-control and operations docs.
+
 ## 3. Open Earth

 Visit:
@@ -79,6 +91,7 @@ Once in, verify:
 - The globe renders correctly
 - The right-side layer panel can toggle layers on/off
 - Search can find cables, satellites, compute centers, BGP events
+- Compute-center and BGP collector detail cards can collect and preview coordinate candidates; the compute-center unresolved badge can open the queue and save candidates
 - Mouse drag, wheel zoom, and zoom percent feedback work correctly
 - Settings panel can switch cruise mode, day/night mode, satellite display style

@@ -176,6 +189,14 @@ To allow a Windows browser, phone, or another device on the same network:

 This makes the frontend and backend listen on a LAN-accessible address.

+Note: `--allow-lan` only makes Planet listen on `0.0.0.0`; it does not automatically expose WSL services through the Windows LAN IP. A common pattern is:
+
+- `localhost:3000` / `localhost:8000` works inside WSL
+- `localhost:3000` / `localhost:8000` works on Windows
+- `http://<Windows LAN IP>:3000` fails from a phone or another computer
+
+That usually means Windows still needs port forwarding or firewall rules.
+
 If access fails, check from the shell running Planet:

 ```bash
@@ -184,6 +205,16 @@ curl http://localhost:8000/health
 ss -ltnp | grep -E ':3000|:8000'
 ```

+If WSL is listening on `0.0.0.0:3000` and `0.0.0.0:8000` but the LAN IP still fails, configure Windows forwarding and firewall rules from an elevated PowerShell:
+
+```powershell
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
+netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000
+
+New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
+New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
+```
+
 ## 9. Stop Services

 ```bash