# Planet Manual

This manual is for Planet end users. Starting from the browser, it covers account registration, login, configuring collectors, configuring AI, using Earth and the console, and reading the docs site. Every action happens in a browser.

If you are responsible for deployment or on-call duty, read the [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md) instead — it covers shell commands, log paths, and CLI fallbacks for user creation.

## Entry Overview

| Name | URL | Login Required | Description |
| --- | --- | --- | --- |
| Earth | `http://<host>/earth` | No | Public 3D situational awareness page |
| Docs | `http://<host>/docs` | Partly | Public docs need no login; developer/ops docs need Gatekeeper groups |
| Register / Login / Forgot Password | `/register`, `/login`, `/forgot-password` | No | Self-serve account creation and recovery |
| Console | `http://<host>/admin` | Yes | Data, collectors, alerts, AI, users, settings |
| AI | `http://<host>/ai` | Yes | Model providers, tools, testbench |
| Backend API Docs | `http://<host>:8000/docs` | Depends | FastAPI / OpenAPI |

URLs below use the local default `http://localhost:3000`. Replace the prefix with your deployment URL in production.

## Register an Account

1. Open `http://localhost:3000/login` and click "Register" under the form.
2. On `/register`, fill in:
   - **Username**: 3–50 characters, used to log in
   - **Email**: receives the verification code; editable later in account settings
   - **Password**: at least 8 characters
3. After submission you are taken to the verify page. A 6-digit code is sent to your email. It expires in 10 minutes.
4. Enter the code and click "Verify and Sign In". On success the system stores a session and sends you to the console.

If no email arrives within 60 seconds:

- Check spam, promotions, and any enterprise mail gateway
- The "Resend Code" button shows a 60-second countdown; you can resend after it ends
- After 5 wrong attempts the code is invalidated; you must resend a new one

If you see "Email service not configured", the administrator has not yet set up SMTP. Ask the administrator to fill SMTP at `/settings -> SMTP Email`.

The default role for a self-registered user is `viewer`, which can sign in and view public content. To see collector / user / settings pages, ask an `admin` or `super_admin` to promote your role at `/users`.

## Sign In and Recover Password

### Sign In

Open `/login`, enter username and password. On success you are taken to `/admin`.

If you see "Email not verified", the page automatically redirects to `/verify-email` — follow the prompts to enter the code.

### Forgot Password

1. On `/login`, click "Forgot Password?", or open `/forgot-password` directly.
2. Enter your registered email and click "Send Code". The same confirmation is shown regardless of whether the email is registered (to avoid enumeration).
3. After receiving the code, enter it together with a new password (≥ 8 characters) and click "Reset Password".
4. The system sends you back to `/login` — sign in with the new password.

## Account Settings

Click your username at the top-right of the console to open account settings:

- Change password: enter current password + new password
- Change email: the system sends a verification code to the new address; the change applies only after verification
- View Gatekeeper groups: lists current groups (`docs_user` / `docs_developer` / `docs_admin`)
- Log out: clears the current session

## Console Overview

The console at `http://localhost:3000/admin` is built with React + Ant Design. The left menu is organized by work domain.

| Page | Route | Purpose |
| --- | --- | --- |
| Dashboard | `/admin` | System overview |
| Earth | `/earth` | Open the public Earth page |
| Datasources | `/datasources` | Source directory and collection triggers |
| Collected Data | `/data` | Data already ingested |
| BGP | `/bgp` | BGP situational view |
| System Alerts | `/alerts/system` | System-level alerts |
| BGP Alerts | `/alerts/bgp` | BGP-related alerts |
| Situational Alerts | `/alerts/situational` | Situational analysis alerts |
| AI | `/ai` | Model providers, tools, testbench |
| Earth Content | `/earth-content` | TV livestreams, boundary precision, base-map and layer-resource entry points |
| Collection Management | `/collection-management` | Collectors, scheduling, collection history entry points |
| Logs | `/logs` | Usually visible only to super admin |
| Users | `/users` | Create/delete users, change roles/groups |
| System Settings | `/settings` | Display, notification, security, SMTP |

Menu items hide automatically when you lack permission. If a menu is missing, check your role and Gatekeeper groups.

## Configure Data Collectors

`/collection-management?tab=collector_credentials` is the "Collectors" page. It manages connection configuration for every collector, not just credentials. Legacy `/settings?tab=collector_credentials` redirects here; the datasource directory remains at `/datasources`.

Steps:

1. Pick a collector in the dropdown.
2. Inspect status tags:
   - `No credentials` / `Credentials required`
   - Owning module
   - `Enabled` / `Disabled`
   - `Unchecked` / `Reachable` / `Unreachable`
3. Click the plug icon next to the dropdown to run a health check. On success the status becomes `Reachable`.
4. Edit endpoint, headers, timeout, retries; click save.

For free collectors without credentials, the health check hits the endpoint directly. For credential-bearing collectors it runs the credential flow. If credentials or endpoint changed since the last successful check, click connect again.

"Connected" means either: data was successfully collected with the current config, or the connect button passed validation with the current config.

### BarentsWatch AIS Credentials

`BarentsWatch AIS` is a credential-required built-in collector. Selecting it surfaces the credential section above the base configuration:

- `Client ID`
- `Client Secret`
- `Endpoint`

If a secret was saved previously, the input shows a masked preview. Saving while keeping the preview unchanged preserves the original secret; entering a new secret overwrites it.

When the connection fails, the page opens a credential guide. You can:

- View the default guide
- Click "Guide not helpful" to ask AI Provider to regenerate from the default prompt
- Click "Reset" to restore the default guide

The default guide follows the BarentsWatch official tutorial and reminds you to choose `AIS - API` for Live AIS.

### AISStream Realtime Vessels

`AISStream Realtime Vessels` is the global AIS WebSocket collector. A passing connection test only confirms API key + endpoint format. Actual global vessel data requires the backend `aisstream_vessels` collector to stay connected and write to `ais_raw_observations`.

Steps:

1. Open `/collection-management?tab=collector_credentials` and select `AISStream Realtime Vessels : aisstream_vessels`
2. Fill the AISStream API Key
3. Keep the default endpoint `wss://stream.aisstream.io/v0/stream`
4. Click the plug icon to test; confirm it reports `Reachable`
5. Save collector settings
6. Open the `Realtime Streams` tab on `/datasources` and find `AISStream Realtime Vessels`
7. Use `Start`, `Stop`, or `Reconnect` there. The normal `Collection Tasks` tab does not count AISStream in one-click collection or percentage progress
8. Watch the realtime stream panel:
   - `streaming` / `connected` means the live stream is being consumed
   - `total stored`, `last 24h`, `last 1h`, and `unique MMSI` show historical collection volume
   - `disconnected` with a recent error means the upstream or network dropped; click `Reconnect`

## Configure AI Credentials

`/ai?tab=providers` is the AI management entry. Three key sub-tabs:

- `Model Providers`: default LLM provider, model, base URL, API key, local `aiprovider` proxy, connection test
- `Tools`: a dropdown for specific tools — currently WebSearch and OCR
- `Prompts`: a task dropdown for news localization, alert analysis, BGP briefs, and other LLM tasks. Operators can edit the prompt or reset it to the default

### Model Providers

Providers and models accept presets or arbitrary custom IDs. Common fields:

- Provider: e.g. `minimax`, `openai`, `anthropic`, `ollama`
- Protocol: `OpenAI Chat Completions` / `Anthropic Messages` / `Ollama Generate`
- Base URL: model API URL
- Default Model: e.g. `gpt-5.1`, `MiniMax-M2.7`
- API Key: stored on save; displayed masked afterwards
- Max Tokens, Anthropic Version: keep defaults if unsure
- Timeout / Retry: timeout and retry attempts

The plug icon at the end of the Base URL input runs a connection test. A passing test echoes the model's short reply.

### Tools

- **WebSearch**: provider, API key, base URL, max results, timeout, advanced provider parameters. While disabled, all fields except the enable switch are greyed out
- **OCR**: provider, base URL, API key, model/engine, recognition languages, timeout, max file size, output format

### Prompts

After selecting a task, the page shows the effective prompt, whether it is customized, the shipped default version, and a reset button. Saving affects only that task. Reset restores the default prompt from the current release package. Business facts, context, and output schemas are still assembled by the backend for each task.

The legacy link `/settings?tab=ai` redirects to `/ai?tab=providers`.

## System Settings

`/settings` manages system-level configuration. Sub-tabs:

- **System Display**: name, refresh interval, retention, max concurrent tasks
- **Notifications**: alert email switch, recipient, critical/warning/daily summary
- **Security**: session timeout, max login attempts, password policy
- **SMTP Email**: outgoing email used by registration and password reset (visible to `admin` / `super_admin` only)

TV livestreams and boundary precision moved to `/earth-content`; collectors and scheduling moved to `/collection-management`; AI Provider / WebSearch / OCR live at `/ai`.

### Earth Content

`/earth-content` is under the console's Operations and Configuration group and owns resources used by the Earth frontend:

- **TV Livestream**: manages sources shown in the Earth media panel.
- **Boundary Precision**: shows the current provider, low-precision fallback, high-precision PMTiles/manifest status, local source JSON, and manual build action.
- **Base Map**, **Layer Resources**, **3D Assets**, and **News Anchor Strategy**: placeholder tabs for future configuration. They do not display fake data.

The Earth page settings gear also includes Boundary Precision. Switching to High Precision starts a local background download/build, like a game update package, when no high-precision asset exists yet. Progress is shown as a percentage, and the result applies automatically after success without a page reload. Switching back to Low Precision only changes the local display preference.

### Collection Management

`/collection-management` is also under Operations and Configuration and owns the collection lifecycle:

- **Collectors**: endpoint, headers, credentials, timeout, retry, and connection checks.
- **Collection Scheduling**: the existing scheduling configuration.
- **Collection History / Snapshots**: a placeholder for future collection task, snapshot, and collected-data browsing.

### SMTP Email Settings

Public registration and verification codes depend on this section. An `admin` or `super_admin` opens `/settings -> SMTP Email` and fills:

- SMTP host, port
- Username, password
- From address (required), from name
- STARTTLS (typical for port 587) or implicit TLS (port 465)
- Timeout in seconds

Save, then click "Send Test Email" and enter a recipient address to verify delivery. Once that works, regular users can self-register at `/register`.

Leaving the masked password preview unchanged keeps the original password. Enter a new value to replace it.

## User Management (Admins)

`/users` is `super_admin`-only for create/delete. The page supports:

- Listing users (username, email, role, active, email verified)
- Creating users (equivalent to public registration but skips email verification — administrator vouching)
- Changing roles: `viewer` / `operator` / `admin` / `super_admin`
- Editing Gatekeeper groups: `docs_user` / `docs_developer` / `docs_admin`, controlling which docs are visible
- Disabling / enabling accounts

To let a regular user read developer or operations docs, add `docs_developer` or `docs_admin` at `/users`.

## Data Exploration

- `/datasources`: source directory. The `Collection Tasks` tab is for one-shot, scheduled, and finite collectors; it can be filtered by product domain, layer/module, enabled state, last run status, whether collected records exist, and search text. Selecting rows triggers only those sources; with no selected rows, `Collect current filter` triggers the filtered scope. The `Realtime Streams` tab is for AISStream / WebSocket long connections and shows connection health, stored totals, time-window counters, and Start / Stop / Reconnect actions. Clicking a name opens an info drawer showing endpoint, headers, base config, and built-in flag; endpoint/credentials editing happens at `/collection-management -> Collectors`. The `Collecting N` tag under the overall progress can be clicked to expand the current collection task list
- `/data`: collected data table — used to verify "did data arrive", "is the freshness right", "does a source emit valid records"
- `/bgp`: BGP detail page with list + detail + analysis; complements the BGP layer on Earth
- `/alerts/system`, `/alerts/bgp`, `/alerts/situational`: system, BGP, and situational alerts

## AI Testbench

`/ai?tab=playground` is for real-pipeline debugging:

- Pick the active provider
- Run preset requests or custom prompts
- Watch AI Provider status and response

The legacy link `/playground` redirects here.

## Earth Public Page

Earth at `http://localhost:3000/earth` is the public 3D situational page; no login required. The React route `/earth` wraps a standalone frontend (in `frontend/public/earth/`) via iframe.

### Primary Uses

A single globe view of: BGP events and observations, satellites and tracks, cables and landing points, compute centers, country boundaries / graticules / high-res tiles / clouds / terrain, news live streams and situational news, search and focus details.

### Layer Control

The right-side layer panel toggles layers. Common layers: graticule, country boundaries, high-res tiles, atmospheric clouds, cables, compute centers, BGP, satellites, AIS vessels, terrain. Satellite tracks are no longer listed as a standalone layer; they are controlled from Settings.

Dependencies:

- Terrain depends on high-res tiles
- Tracks depend on satellites
- With high-res tiles disabled, the globe shows the base map with edge highlighting

### Legend

The bottom-left legend follows the focused or enabled layer. Covered: cables, satellites, country boundaries, compute centers, BGP, AIS vessels.

AIS vessel legend colors by type: cargo, tanker, passenger, fishing, military, moored/slow, other. Triangles indicate moving vessels; dots indicate moored or slow targets.

### Search

Search finds cables, landing points, satellites, compute centers, BGP events, BGP observers. Results jump to and focus the object.

### Coordinate Candidate Collection

Compute center and BGP observer detail cards support automatic coordinate-candidate collection. Click the object then use "Collect Coordinate Candidates" or "Re-collect Coordinates". The backend assembles candidates from source coordinates, public-org registry APIs, and online geocoders. When regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback. BGP observers' stored coordinates only fill query context; they are not returned as candidates.

Candidates preview on Earth directly. Saving a compute-center candidate writes to the `compute_center_locations` dimension table and refreshes the layer immediately. The notification badge at the top-left of the compute-center layer shows the unresolved count; clicking it opens the queue, supports single collection, or "Adopt All" to save the top-confidence candidates from top to bottom. Records without candidates stay in the queue rather than being faked to country centroids. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md).

### Settings

The settings panel covers: rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, hover tooltip, satellite idle breathing, real satellite altitude, track display, compact dots, day-night mode, panel toggles), motion debug mode / input source / skeleton-only, default globe size, terrain opacity, reset.

"Real Satellite Altitude" is enabled by default: satellite positions use a compressed display height based on TLE/SGP4 orbital altitude. LEO satellites remain close to the globe, while high-orbit satellites render farther out without leaving the normal view. The high-orbit display height is capped at about one quarter of the globe radius, so GEO / MEO objects remain visually separated from LEO without spreading trails and selection targets too far apart. Turning it off restores the legacy same-sphere satellite display. "Track Display" controls satellite trail visibility; trails are unavailable while the satellite layer is hidden.

"Hover Tooltip" controls the tooltip shown when the pointer hovers over the globe surface: `Country` shows country details only when land matches a country, and stays silent over oceans such as the Pacific; `Position` shows latitude, longitude, and elevation over land and ocean; `Full` is the default and shows country + position over land and position over ocean.

These settings live in browser local storage; switching browsers or clearing site data resets them.

### View Controls

| Action | Effect |
| --- | --- |
| Mouse drag | Rotate the globe |
| Single-finger drag | Touch rotate |
| Mouse wheel | Zoom in/out |
| Pinch | Touch zoom |
| Zoom button | Stepped zoom |
| Click zoom percentage | Reset to default zoom |

A small pill at the top briefly shows the current zoom while zooming. This is not a data loading indicator; if data is loading, the loading state takes precedence.

Drag sensitivity adjusts to zoom: near the default it is normal; zoomed in it is finer for targeted inspection; zoomed out it is slightly faster for global browsing.

### Motion Capture

Earth supports motion capture. Two live inputs:

- **Browser Camera** (default): uses `getUserMedia` in the page. No install needed but the page must run on HTTPS or localhost, and the user must grant camera permission
- **Motion Agent**: camera/RTSP/HTTP → local agent → local WebSocket → Earth. Used for dual cameras, USB index, phone/IP camera streams

Enable via the settings toggle "Motion Debug Mode", or with URL parameter `?motion=1`. Motion Agent defaults to `ws://127.0.0.1:8765/ws/gestures`; override with `motionAgent`. You can also pin the input with `?motion=1&motionProvider=browser` or `?motion=1&motionProvider=agent`.

Neither mode uploads camera frames or live gestures; neither reuses the news/RSS aggregation API.

Gesture semantics:

| Event | Effect |
| --- | --- |
| `rotate_left/right/up/down` | Rotate accordingly |
| `zoom_in/out` | Zoom |
| `focus_prev/next` | Cycle focusable targets within the current layer |
| `layer_prev/next` | Switch layer and pan to nearest target |
| `confirm` | Confirm the current selection |

In the debug panel: the browser camera input shows the live preview with skeleton overlay; Motion Agent sends only normalized skeleton events, never raw frames. "Skeleton Only" hides the video and keeps just the skeleton; "Stop Matching" pauses gesture firing while keeping preview and skeleton. Unmatched skeleton is red; matched turns green and shows the action name.

### Cruise Mode

Cruise mode auto-rotates focused targets. Current modules: BGP, news, compute centers, vessels, cables, satellites. Suitable for demos, control rooms, and unattended displays.

### Mobile

Mobile uses a drawer layout: layer control moves into a drawer; search/settings/details use mobile panels. Main interaction is still object tap, search, and layer toggles.

### Common Issues

- **Earth does not open**: confirm the frontend is online; if not on port `3000`, use the port printed by the startup log
- **Layers have no data**: open `/datasources` to check source status, collected-record state, and the latest run result; then `/data` or `/bgp` for records
- **Satellites / BGP / cables load slowly**: those layers depend on backend APIs and external data sources; the first load waits for startup tasks
- **Satellites are not all on one shell**: this is the default compressed real-altitude display. Disable "Real Satellite Altitude" in Settings to return to the legacy same-sphere view

## Docs Site

Docs at `http://localhost:3000/docs` are served by the backend with access control, not bundled into the frontend build.

Anonymous visitors see only `public` docs: README, Quickstart, Manual, FAQ, Earth Location Candidate Collection User Guide. Authenticated users with Gatekeeper groups see more:

- `docs_user`: end-user operational docs
- `docs_developer`: Earth, frontend, backend, collectors, AI Provider development docs
- `docs_admin`: service control, operations, environment variables, sensitive operations (including the Ops Runbook)

`admin` has `docs_admin` by default; `super_admin` has all docs permissions. Gatekeeper groups are managed at `/users`.

Docs supports: category navigation, Markdown rendering, tables and code blocks, in-doc table of contents, search across currently visible docs, internal links between technical docs.

## Related Docs

- [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
- [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md)
- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
- [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md)