Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / desktop-and-external-clients

Desktop and external clients

WorldMonitor extends beyond the main web application through a native desktop app, browser-plugin views, a command-line client, language SDKs, and automation integrations. These surfaces use the same intelligence services in different settings: desktop analysis, host-embedded views, shell automation, application integration, agent use, and workflow automation.

Surface model

Each surface presents WorldMonitor data through a contract suited to its host. The desktop app preserves the dashboard experience, browser plugins place focused intelligence views inside an agent host, and the CLI and SDKs turn service calls into reusable interfaces.

SurfaceMain user or hostPrimary purpose
Desktop applicationAnalyst on macOS, Windows, or LinuxPackaged dashboard with native desktop support and local service access
Browser-plugin viewsAgent host such as ChatGPTEmbedded news, map, country-intelligence, and market views
Command-line clientShell user, script, CI job, or agentInteractive terminal dashboard and structured output for repeatable tasks
SDK clientsApplication or serviceLanguage-native access to WorldMonitor tools and API paths
Automation integrationsWorkflow platform or external systemScheduled or event-driven use of WorldMonitor actions

The web application shell remains the main interactive surface. The API platform supplies the shared hosted contract that the desktop fallback path and reusable clients consume. The client experience page gives the wider view of how these surfaces fit user-facing product flows.

Desktop distribution

Native desktop application

The desktop application is a Tauri shell around the WorldMonitor dashboard. It packages one WorldMonitor application for macOS, Windows, and Linux, then lets the user choose the product variant after installation. Native concerns such as windows, menus, credentials, startup, and updates stay outside the shared dashboard experience.

The native package uses a common Tauri desktop runtime and includes the local service and shared data needed by the dashboard. Its platform bundles cover macOS app and DMG outputs, Windows installers, and a Linux AppImage. The package uses a single binary for all product variants rather than a separate binary for each variant.

At startup, the native shell launches a local service and accepts its port only after the service confirms it. If the first readiness wait expires, a bounded recovery watcher can accept a later confirmed port, but the shell never sends token-bearing traffic to an unverified default port. The shell also creates a per-session transport token and keeps provider credentials in the operating-system key store. On Linux, it can use the session keyring when Secret Service is unavailable, with a warning that this storage does not survive a reboot.

On Linux, the shell also applies platform-aware rendering settings for virtual machines, NVIDIA and Wayland sessions, and AppImage media support. These settings keep the dashboard and embedded media usable across desktop environments with different graphics capabilities.

See the Tauri desktop application page for startup, local service, credential, and release details.

References: src-tauri/tauri.conf.json• L1-12 src-tauri/tauri.conf.json• L35-66 src-tauri/Cargo.toml• L1-31 src-tauri/Cargo.lock• L1962-1977 src-tauri/…/main.rs• L2597-2729 scripts/desktop-package.mjs• L21-65

Desktop sign-in

Desktop sign-in uses the system browser for flows that the embedded WebView cannot complete. Clerk, the sign-in service, returns the result through a short-lived loopback callback. The native shell checks the callback and exchanges it before the renderer receives only the sign-in outcome.

The flow keeps sign-in credentials outside renderer script. The shell uses proof of possession and a one-time state value to bind the callback to the active request. It then keeps the Clerk client token in the operating-system key store so a user can remain signed in across launches. The Tauri desktop application page covers this lifecycle with the other native desktop concerns.

This diagram shows how a desktop sign-in moves between the user, the system browser, and the native shell.

sequenceDiagram
    participant U as User
    participant B as System browser
    participant D as Tauri shell
    participant C as Clerk
    U->>D: Start sign-in
    D->>B: Open WorldMonitor sign-in page
    B->>C: Complete sign-in
    C-->>B: Redirect to loopback callback
    B->>D: Return one-time code
    D->>C: Exchange code and redeem ticket
    C-->>D: Authenticated client session
    D-->>U: Return sign-in result to dashboard

References: src-tauri/…/desktop_sign_in.rs• L1-9 src-tauri/…/desktop_sign_in.rs• L48-118 src-tauri/…/desktop_sign_in.rs• L163-267 src-tauri/…/clerk_relay.rs• L55-174 src-tauri/…/main.rs• L739-919

Local service boundary

The desktop process runs a local service beside the native shell. The dashboard sends requests through the Tauri bridge, and the local service handles them locally when possible or uses the hosted API when the desktop request allows that fallback. The Tauri bridge is a bounded API gateway rather than a general local HTTP tunnel: it accepts normalized /api/ paths, excludes secret-management routes, and limits request and response bodies. Self-hosted Docker mode keeps normal cloud fallback off, but it can relay selected hosted paths when the browser has stored the user's own desktop key.

The boundary fails closed. Protected routes require the per-session transport token, the native shell refuses to use a port that the child process did not confirm, and a late readiness watcher still requires a verified port before it enables requests. The bridge accepts proxy calls only from trusted desktop windows and does not expose the sidecar's secret-management routes through the general request path. The service removes that transport credential before a local handler sees the request. Health, status, and the media bridge remain narrow exceptions because monitoring and embedded media cannot carry the same request headers. If the sidecar starts without its local token, it rejects protected requests rather than becoming an open local proxy.

The native bridge also bounds connection and request time. A stalled local service therefore returns an error instead of holding a desktop request open without limit.

The desktop cloud path is separate from local secret handling. A signed-in Pro user can pass a Clerk bearer to the hosted service through a dedicated user-authorization header. Requests that do not have that entitlement use the public desktop path, while local-only routes never send the cloud credential. The sidecar can also mint and reuse the short-lived anonymous session needed by the hosted gateway.

Docker self-hosting adds a user-owned key relay for selected hosted paths. The sidecar validates the key with the cloud, keeps only the key's status for a short time, and sends the key only to the hosted service. This keeps native administration routes unavailable in Docker while allowing the self-hosted dashboard to use the user's cloud allocation.

The local RSS feed bridge has a narrower public role. It validates feed destinations against public-network rules, and Docker mode also uses the hosted feed allowlist, default-port rule, and per-client limits. Feed bodies and concurrent work are bounded so one viewer cannot consume the whole local service.

Seed-backed hosted data stays on the cloud path when the local service does not hold the hosted snapshot. This includes cached maritime incident reports and other cloud-owned snapshots, so an empty local result does not hide data that is available from the hosted service. Local Ollama headline translation is an explicit local path and does not move to the cloud.

The service protects its outbound work. It blocks private and reserved network targets by default, pins validated public addresses for the request, limits upstream concurrency and idle time, and prefers the hosted service for data that depends on cloud-owned snapshots. The feed bridge applies the same address validation to public feeds and caps response size. Read requests can use local fallback when a cloud-preferred request fails, while side-effecting requests are not retried after the cloud attempt.

The desktop request path combines local and hosted work as follows:

flowchart LR
    A[Desktop dashboard] --> B[Tauri bridge]
    B --> C[Authenticated local service]
    C --> D[Local handler]
    C --> E[Hosted WorldMonitor API]
    D --> F[Dashboard result]
    E --> F

The local service keeps the same boundary for desktop and Docker use, but Docker mode has a narrower role. It exposes public proxy behavior without granting native administration, disables hosted fallback, and permits private upstream access only for configured self-hosted services.

The service also provides a small media bridge for YouTube embeds. It validates video or channel identifiers and accepts messages only from known desktop or local parent origins. This lets embedded media work without exposing the protected API routes to an iframe.

References: src-tauri/…/main.rs• L28-35 src-tauri/…/main.rs• L514-612 src-tauri/…/main.rs• L2200-2424 src-tauri/…/local-api-server.mjs• L31-55 src-tauri/…/local-api-server.mjs• L241-377 src-tauri/…/local-api-server.mjs• L839-983 src-tauri/…/local-api-server.mjs• L1024-1355 src-tauri/…/local-api-server.mjs• L1372-1593 src-tauri/…/local-api-server.mjs• L2263-2377 src-tauri/…/local-api-server.mjs• L2543-2630 src-tauri/…/local-api-server.mjs• L2709-2787 src-tauri/…/local-api-server.mjs• L2960-3036 src-tauri/…/local-api-server.test.mjs• L20-62 src-tauri/…/local-api-server.test.mjs• L221-317 src-tauri/…/local-api-server.test.mjs• L365-516 src-tauri/…/local-api-server.test.mjs• L518-682

Browser-plugin integrations

Host-embedded views

The browser-plugin surface provides focused WorldMonitor views for a host that can call MCP tools and display an embedded page. The view communicates with its host through a JSON-RPC message boundary, so the host supplies data access while the plugin supplies the rendered map, news panels, country brief, or market snapshot.

The plugin checks host capabilities during initialization. Server tools enable data reads and analysis, link support controls source navigation, and model-context support lets the view report its current state back to the host. Each view also advertises a small set of actions that the host can call. If a capability is absent, the view keeps the related action unavailable instead of making a direct request outside the host boundary. This is the agent-facing integration described in AI-agent plugin integration.

References: src/plugin-main.ts• L495-557 src/plugin-country-main.ts• L605-709 src/plugin-market-main.ts• L178-200

Global news and map view

The global plugin gives an agent host a compact news and map workspace. It displays the host-provided news snapshot, filters it by source, category, country, and time range, and can show a flat map or globe with selected hazard and reference layers. Host actions can apply a view or focus an article that is already in the current snapshot.

The view keeps news filters separate from hazard coverage. A country filter changes which news items are shown, while hazard layers use a bounded global snapshot. This lets the host report the scope and coverage of map data instead of implying that an empty view means no activity. The view also keeps prior news visible when a refresh fails and reports stale or partial coverage to the host.

References: src/plugin-main.ts• L63-140 src/plugin-main.ts• L148-221 src/plugin-main.ts• L231-358 shared/plugin-news-view.ts• L3-35 plugin.html• L10-20

Country intelligence view

The country plugin turns a country request into a hosted country brief. It loads country facts, risk, assessment, news, events, economic data, and other topic sections through host tools. Sections load independently, so one unavailable or restricted source does not hide the other available observations.

The view manages country changes and refreshes as separate requests. It cancels work for a prior country, keeps prior observations visible during refresh, labels unavailable or locked sections, and sends a bounded summary of the rendered state back to the host when supported. Country selection can come from the map or a host action. The browser-plugin country intelligence page describes this flow and its section model in more detail.

References: src/plugin-country-main.ts• L63-299 src/plugin-country-main.ts• L314-385 src/plugin-country-main.ts• L464-603 src/plugin-country-main.ts• L605-709 src/…/country-intel.ts• L294-327 src/…/country-intel.ts• L373-415 e2e/plugin-country-view.spec.ts• L90-130 e2e/plugin-country-view.spec.ts• L132-165

Market snapshot view

The market plugin gives an agent host a compact snapshot of financial indicators. It presents grouped equity, commodity, crypto, Gulf, sector, and projected quote data when supplied by the host, with optional Fear and Greed context and small price-history charts.

The view treats the response as a bounded observation rather than a live market feed. It shows provider limits, source coverage, observation time, stale state, and missing chart data so the host can distinguish an absent value from a zero or a complete market picture. Chart expansion reuses the loaded snapshot and does not request a new market feed.

References: src/plugin-market-main.ts• L11-18 src/plugin-market-main.ts• L38-73 src/plugin-market-main.ts• L75-176 src/plugin-market-main.ts• L178-200

Reusable client interfaces

MCP and REST interfaces

The Model Context Protocol (MCP) is the main tool interface for external clients. It lets a client discover tools and call them with structured arguments. REST remains available for direct API paths, health checks, and deployments that need a host-relative or self-hosted base URL.

MCP and REST are two ways to consume the same service rather than separate data products. A client chooses MCP for tool discovery and named intelligence actions, or REST when it needs a specific path and response contract. AI-agent plugins use the same MCP tool boundary while adding a host-facing view and action model; see AI-agent plugin integration.

flowchart TD
    A[Script, agent, or application] --> B[CLI or SDK]
    B --> C[MCP discovery or tool call]
    B --> D[REST path or health request]
    C --> E[Structured WorldMonitor result]
    D --> E

References: cli/…/core.mjs• L1-10 cli/…/core.mjs• L231-305 sdk/…/worldmonitor.go• L137-198 sdk/…/__init__.py• L179-225 sdk/…/worldmonitor.rb• L97-141 api/…/index.ts• L12-30 api/…/index.ts• L32-66 docs/cli.mdx• L20-41 docs/sdks.mdx• L19-29

Agent skill catalog

An agent skill is a named, reusable recipe that guides an agent through a WorldMonitor task. MCP exposes these recipes through a bounded discovery surface while keeping the complete recipe content available by URI.

The catalog uses three related operations:

  • skills/list returns the first five skill entries and rejects continuation cursors. This keeps the complete discovery response within its publishing bound.
  • skills/get retrieves any known skill entry by its URI.
  • resources/read returns the text or binary content for a skill resource.

This split keeps initial discovery small without removing access to the full skill collection. AI-agent hosts can discover the stable first-page contract, then request the exact recipe or resource that they need.

References: api/…/index.ts• L1-30 api/…/index.ts• L32-66 api/…/generated.ts• L1-16

Command-line client

The official worldmonitor package serves two related needs. Its commands use MCP first for scripts and agents, while REST provides health checks and direct paths for host-relative or self-hosted use. Its terminal dashboard gives a human a live, keyboard and mouse driven view of the same intelligence data. A bare command opens the dashboard only in an interactive terminal; piped or scripted use prints help unless the dashboard is forced. The dashboard can use public bootstrap tiers without an API key. Data commands still use the subscription key rules of the service.

The dashboard covers overview, map, brief, news, markets, conflict, air and sea activity, cyber, climate, predictions, live channels, intelligence, and system health. Its map supports a flat view or rotating globe, satellite imagery, searchable layers, and detail cards. The brief view connects AI story lines to cited sources and related headlines. The live view groups news channels by default, region, or all sources and includes webcams. Users can play a selected stream in the terminal, an mpv window, or the browser, then cycle to another source when playback fails. The generated catalog supplies the dashboard with regional channels, webcam sources, map data, and layer data.

JSON output supports shell pipelines and agents, while distinct exit results let automation separate request failure from invalid usage. Requests have a bounded timeout, and MCP responses can arrive as streamable HTTP events before they are returned as structured output. The client handles specification redirects without forwarding an API key to a new origin. The package also exposes discovery views for tools, prompts, resources, and OpenAPI paths. Its request-planning layer can be reused by JavaScript programs. The terminal dashboard page explains the shell dashboard workflow, and the Zapier automation integration page explains how external automation can consume WorldMonitor actions without using the main web interface.

References: cli/package.json• L1-49 cli/README.md• L7-20 cli/README.md• L32-84 cli/README.md• L91-170 cli/…/core.mjs• L1-31 cli/…/core.mjs• L42-95 cli/…/core.mjs• L127-324 cli/…/core.mjs• L365-420 cli/…/run.mjs• L23-71 cli/…/run.mjs• L74-185 cli/…/index.mjs• L17-50 cli/…/app.mjs• L37-76 cli/…/store.mjs• L8-37 cli/…/store.mjs• L93-127 cli/…/index.mjs• L15-30 cli/…/map.mjs• L22-107 cli/…/brief.mjs• L67-143 cli/…/live.mjs• L15-145 cli/…/catalog.generated.json• L1-12

Language SDK clients

The official Python, Ruby, Go, and JavaScript SDKs provide the same client model in language-specific forms. Each SDK supports common intelligence queries, generic MCP tool calls, public discovery, and a REST escape hatch. This shared shape lets an application change languages without changing how it uses WorldMonitor. The SDK client libraries page describes the language-specific entry points.

Applications provide an API key through the client configuration or shared environment configuration. The clients keep MCP errors distinct from REST and transport errors, parse streamable HTTP responses, and do not follow redirects that could forward a key to another host. This lets a service respond to authorization, connection, and endpoint-boundary problems in different ways.

LanguagePackage or importTypical use
Pythonworldmonitor-sdkData scripts and Python services
RubyworldmonitorRuby applications and jobs
Gogithub.com/koala73/worldmonitor/sdk/goGo services and command tools
JavaScriptworldmonitorNode.js programs and the CLI

References: docs/sdks.mdx• L1-29 sdk/…/README.md• L39-55 sdk/…/__init__.py• L84-105 sdk/…/__init__.py• L114-175 sdk/…/__init__.py• L283-308 sdk/…/worldmonitor.rb• L75-141 sdk/…/worldmonitor.rb• L202-254 sdk/…/version.rb• L1-5 sdk/…/README.md• L46-55 sdk/…/worldmonitor.go• L39-63 sdk/…/worldmonitor.go• L97-135 sdk/…/worldmonitor.go• L270-313 sdk/…/README.md• L60-76

Surface relationships

All surfaces depend on WorldMonitor intelligence contracts, but they do not share the same host assumptions. The desktop app can run a local service and use operating-system credential storage. Browser plugins depend on host-provided tools and message capabilities. The CLI dashboard runs in the caller's terminal and uses public bootstrap data for its initial view. CLI commands, SDKs, AI-agent plugins, and workflow integrations call hosted MCP or REST endpoints through their own host boundary.

This separation limits the effect of a surface-specific change. A change to a hosted tool or API contract can affect every surface. A change to desktop startup, plugin host support, market snapshot shape, terminal catalog or view behavior, client argument handling, or skill discovery affects only the related boundary.

Change checklist

When these files or sections are changed, remember to consider these:

  • When an MCP tool name, argument, skill name, skill URI, or access rule changes, check the plugin actions, curated CLI commands, SDK helpers, discovery output, automation mappings, and API guidance together.
  • When browser-plugin host capabilities change, check initialization, tool calls, source-link handling, model-context updates, resize messages, and the unavailable-capability states.
  • When the global plugin view schema changes, check its host tool schema, news filters, map layer scope, hazard snapshot coverage, and view receipt together.
  • When country brief section names or result states change, check host tool calls, independent section rendering, refresh behavior, cancellation, and locked or unavailable messages together.
  • When country model-context groups or size limits change, check visible-section state, omitted and truncated content markers, source-link limits, and the host update receipt together.
  • When market snapshot fields or group names change, check quote grouping, projection handling, coverage messages, chart data, and host result delivery together.
  • When desktop local routes, port discovery, transport authentication, or sidecar exceptions change, check the Tauri bridge, readiness watcher, fallback policy, health paths, media bridge, and Docker behavior as one boundary.
  • When the desktop proxy path allowlist or body limits change, check path normalization, renderer-window permissions, secret-management routes, sidecar authentication, and the local service handlers together.
  • When desktop cloud entitlement or bearer handling changes, check local-only routes, the sidecar user-authorization header, anonymous session minting, entitlement refresh, the Docker self-host key relay, and the hosted gateway contract together.
  • When desktop sign-in changes, check the system-browser callback, PKCE and state checks, allowed Clerk hosts and paths, ticket lifetime, token rotation, and key-store persistence together.
  • When outbound sidecar network rules change, check public-host validation, DNS address pinning, configured Docker origins, cloud-preferred routes, upstream limits, RSS feed allowlists, and registration bridges.
  • When the hosted API key contract changes, check CLI guidance, SDK configuration, plugin host authorization, desktop cloud fallback, automation credentials, and error classification.
  • When MCP or REST base URLs change, check constructor defaults, environment configuration, CLI flags, public docs, automation connections, and self-hosted behavior.
  • When CLI terminal detection, timeout, redirect handling, or streamable response parsing changes, check bare-command behavior, piped help, auth hints, exit codes, spec fetching, and both MCP and REST output paths.
  • When an SDK release or transport contract changes, check language package versions, user-agent values, environment fallback, MCP and REST error types, redirect policy, and the shared SDK guidance.
  • When the terminal dashboard catalog, source schedule, map layer, imagery, live stream source, or view contract changes, check lazy loading, saved map preferences, narrow-terminal layout, playback fallback, detail links, and generated catalog data together.
  • When native dependencies, packaged resources, or the one-binary desktop model changes, check bundle identity, platform targets, updater selection, and the packaging guard against per-variant builds.
  • When desktop key-store behavior changes, check platform storage, Linux session-keyring fallback, migration, warnings, and the sidecar's injected secret state together.
  • When the agent skill catalog changes, check the bounded skills/list response, URI lookup through skills/get, resource payloads through resources/read, and the guidance used by agent hosts.

Important failure modes

TriggerConsequenceGuard
The desktop sidecar has no session token or receives the wrong tokenProtected local routes return an error instead of becoming an open local proxyThe sidecar uses default-deny authentication, and the Tauri shell creates a per-session token
A renderer sends a non-API path, a secret-management path, or an oversized local proxy bodyThe Tauri bridge rejects the request before it reaches the sidecarThe bridge normalizes paths, permits only the bounded API route set, limits bodies, and accepts proxy calls only from trusted desktop windows
The sidecar does not confirm its port during the initial or bounded recovery waitThe dashboard cannot call the local service until a verified port appearsRust refuses to send token-bearing traffic to the guessed port and watches the live child for late confirmation
Docker mode reaches for a private origin that is not configured for that serviceThe local handler cannot reach the upstream, preventing an unintended internal-network proxyPrivate and reserved targets are blocked by default; Docker allows only its configured self-hosted origins
A Docker self-host key is invalid, inactive, or unavailable at the cloudPremium hosted paths stay local or return an unavailable result instead of using another user's allocationThe sidecar validates the key, caches only its verdict, and relays only allowed paths from the same site
An outbound sidecar request stalls after connection or exhausts the upstream poolLater local requests can wait or fail instead of returning a resultPublic targets are address-pinned, upstream work has a concurrency cap and idle timeout, and callers can abort queued work
A Docker RSS request targets a domain outside the feed allowlist or uses a non-default portThe feed is refused before the sidecar fetches itDocker mode applies the hosted feed domain allowlist, default-port rule, and per-client rate limit
A feed resolves to a private address, exceeds the body cap, or fills the feed queueThe feed returns a blocked, oversized, busy, or timeout result instead of consuming unbounded network or memory resourcesDNS results are checked and pinned, response size is capped, and feed concurrency, queue size, wait time, and client share are bounded
A desktop request needs hosted fallback without a valid API key or Pro bearerThe request fails instead of silently using an unauthorized hosted routeThe cloud path forwards only configured or entitled authorization and keeps normal API access checks
A cloud-owned snapshot route is served from an empty local handlerThe desktop view can show an incomplete result without a clear provider errorSeed-dependent routes are cloud-preferred when fallback is enabled
A desktop sign-in callback has the wrong state, host, or lifetimeThe native shell rejects the flow and does not create a sessionThe loopback listener accepts only a matching state and the exchange uses a short-lived PKCE-bound code
The renderer asks the Clerk relay for an unapproved host, method, or pathThe request is refused before it can reach an external hostThe relay allows only known Clerk Frontend API hosts and /v1/ requests
A redeemed desktop sign-in does not return a usable session tokenThe existing session stays active and the new sign-in is not adoptedThe shell changes the stored client only after Clerk accepts the ticket and returns a token
The platform secret store is unavailable on LinuxAPI keys can be lost after reboot or remain unavailable to the local serviceThe shell uses the session keyring only for the detected Secret Service outage and reports the non-persistent storage state
A Linux graphics environment cannot support the default WebKit pathThe desktop can show blank or black dashboard, iframe, or video contentStartup detects common VM, NVIDIA, Wayland, and AppImage cases and selects safer rendering or media settings
A plugin host does not provide server toolsNews refresh, analysis, hazard snapshots, country sections, or market data cannot loadThe plugin detects host capabilities or host result state and leaves unsupported actions unavailable
A plugin host request fails or times outThe embedded view can show old data or an unavailable section instead of a new resultPending calls have time limits, and the country view cancels work when the selected country changes
A country source is locked or unavailableOne brief section cannot be read, but a user may mistake it for zero activitySection states identify locked and unavailable data while other sections remain visible
Country model context exceeds its host size limitThe host receives a reduced summary or no optional detailThe country view bounds rendered text, signal groups, source links, and optional fields before sending context
News, hazard, country, or market coverage is partial or staleThe view may look complete while some observations are missing or oldThe views retain coverage, stale, and source state in status text and rendered context
A market response contains a projection or quote group outside the expected shapeThe panel can show no data or ask for a narrower requestThe market view reports projection and response-size errors and only renders finite, recognized values
A self-hosted registration bridge lacks its shared secret or Convex siteRegistration returns an unavailable or failed resultThe sidecar requires the authenticated self-hosted bridge configuration and validates the returned status
A terminal dashboard source fails during boot or refreshThe related view stays partial and reports a source error instead of blocking every viewThe store loads sources independently, backs off failed requests, and keeps per-source status
Terminal map imagery is unavailable or incompleteThe map remains usable with its tactical base or prior ready imagery, but the selected backdrop is not shownThe imagery cache reports loading or error state and preserves ready tiles while new tiles load
A listed live channel has no playable source or its player is missingPlayback opens a browser fallback or reports a failed stream instead of stopping the dashboardThe live view checks candidate sources, offers browser and mpv modes, and selects the next source after a failed attempt
The terminal is too small for a map sidebar or multi-pane viewSome controls or panels are hidden, but the dashboard remains navigableViews switch to narrow layouts and keep keyboard controls for the main content
A CLI or SDK data call lacks a subscription keyThe service returns an authentication error or the client reports a failed requestPublic discovery and the terminal dashboard bootstrap remain available, and clients expose a clear key configuration path
A CLI or SDK follows a redirect to another host while carrying a keyThe request can expose the key or return an unexpected endpoint responseCLI spec redirects are handled with origin-aware headers, and SDK HTTP clients do not follow redirects
A streamable MCP response is treated as ordinary JSONThe client returns an event wrapper or fails to expose the tool resultCLI and SDK clients select the final data: payload before decoding the result
A client sends a continuation cursor to skills/listSkill discovery fails even though individual recipes remain availableTreat skills/list as a bounded first-page catalog, then use skills/get or resources/read for the needed URI
A registered MCP tool or skill changes without matching plugin, CLI, SDK, or automation guidanceGeneric calls may work while curated actions send stale arguments or agents miss the recipeKeep the shared tool and skill contracts and every client-facing wrapper aligned

Key files

FileWhy to read it
src-tauri/tauri.conf.jsonDefines the desktop identity, bundle targets, and packaged resources.
src-tauri/Cargo.tomlDefines the native desktop dependencies and release profile used by the shell.
src-tauri/Cargo.lockPins the native desktop dependency graph used for repeatable builds.
src-tauri/…/main.rsShows the native shell lifecycle, trusted desktop bridge, bounded local proxy, sidecar readiness, credential boundary, platform rendering workarounds, and key-store fallback.
src-tauri/…/desktop_sign_in.rsShows the system-browser sign-in flow, loopback callback, and short-lived ticket state.
src-tauri/…/clerk_relay.rsShows the allowed Clerk boundary and native client-token relay contract.
src-tauri/…/local-api-server.mjsShows the local service boundary, authentication, hosted fallback, self-host key relay, feed proxy, registration paths, local model path, and outbound access rules.
src-tauri/…/local-api-server.test.mjsShows the security, cloud-preference, local model, self-host relay, feed proxy, and routing contracts that protect local and hosted request paths.
src/…/tauri-bridge.tsShows how the dashboard reaches the local desktop service.
src/…/runtime.tsShows the desktop local-first, credential, and hosted-fallback policy.
src/…/desktop-cloud-auth.tsShows how desktop entitlement state controls the cloud bearer and one-time reload.
scripts/desktop-package.mjsShows the single desktop distribution model.
src/plugin-main.tsShows the host-embedded global news and map view.
src/plugin-country-main.tsShows the host-embedded country brief, bounded host context, and request lifecycle.
src/plugin-market-main.tsShows the host-embedded market snapshot and coverage states.
shared/plugin-news-view.tsDefines the global plugin view contract for filters and map state.
plugin.jsonDescribes the browser-plugin product surface and host-facing capabilities.
vite.plugin.config.tsShows that the plugin build produces the global, country, and market browser views.
api/…/index.tsDefines bounded skill discovery and URI-based skill and resource retrieval for MCP agents.
api/…/generated.tsProvides the generated skill catalog and resource metadata exposed by the skill extension.
cli/package.jsonDefines the published command-line package, executable aliases, and supported Node runtime.
cli/README.mdDescribes the terminal dashboard, shell commands, output modes, and access rules.
cli/…/core.mjsShows how shell input becomes MCP-first or REST request plans, including curated commands and environment configuration.
cli/…/run.mjsShows interactive launch behavior, transport handling, timeouts, response parsing, redirect safety, and exit results.
cli/…/index.mjsShows dashboard startup, terminal ownership, source boot, and shutdown.
cli/…/app.mjsShows view switching, input, detail overlays, preferences, and rendering flow.
cli/…/store.mjsShows source schedules, boot order, lazy loading, refresh, and failure state.
cli/…/index.mjsMaps the dashboard tabs to its high-level intelligence views.
cli/…/map.mjsShows the terminal map and globe surface, layers, imagery, search, and detail interaction.
cli/…/brief.mjsShows how the terminal brief connects story lines to cited and related coverage.
cli/…/live.mjsShows live channel and webcam selection, source fallback, and terminal, window, or browser playback.
cli/…/catalog.generated.jsonProvides the generated regional channel, webcam, map, and live-content data used by the dashboard.
docs/cli.mdxDescribes the command-line automation contract.
docs/sdks.mdxDescribes the shared model across official SDKs.
sdk/…/__init__.pyShows Python client configuration, MCP and REST access, response parsing, and error boundaries.
sdk/…/worldmonitor.rbShows Ruby client configuration, MCP and REST access, response parsing, and error boundaries.
sdk/…/worldmonitor.goShows Go client configuration, MCP and REST access, response parsing, and redirect policy.
sdk/…/version.rbIdentifies the released Ruby SDK version used by the language-client surface.
sdk/…/README.mdGives a clear language-level view of SDK access, configuration, and errors.