Skip to content

Documentation conventions (EDOS workspace)

Audience: Agent + operator

This file defines how documentation in this tree is written so humans and coding agents can rely on consistent structure, terminology, and uncertainty handling.

Workspace model

  • Workspace (edos): A single directory that holds several independent projects side by side. It is not a monorepo: there is no shared root package, workspace-wide build, or enforced single version line across projects.
  • Project / app: One top-level folder under the workspace root (for example elite-dangerous-surface-map, inter-frame-messenger). Each project has its own repository history, tooling, and release lifecycle unless explicitly stated otherwise.
  • Documentation repo (future): Documentation may live in a separate repository that mirrors or references this layout. Paths in docs are written relative to the docs root (docs/) or the workspace root when pointing at code; always state which.

Partial workspace checkouts

The edos directory is often incomplete on disk: only some top-level folders, submodule/git-only placeholders, sparse trees, or a docs-only clone. That is normal — not a documentation error.

Layer Authoritative for
This docs/ tree Ecosystem inventory, IPC, architecture, agent playbooks
Each app repository (<project>/) Run scripts, source layout, docker-compose.yaml / Dockerfile, CI, project README.md

Expected when a folder is missing or thin locally

  • No docker-compose.yaml under <project>/ — deploy files live in the full app repo; your checkout may not include them.
  • Empty or partial ui/src/ — open the full app repository before grepping implementation paths cited in docs.
  • Top-level folder with only .git — clone that app repo; capsules still describe the product.

For agents editing docs/

  • Do not add TODO: Verify only because a compose file or source tree is absent in this workspace.
  • When documenting deploy details (Traefik host, image, port), read README.md and docker-compose.yaml in a full clone of that app — or cite the path without inventing values.
  • Reserve TODO: Verify for real drift: the full app repo is available but docs and code disagree (include a file or grep hint).

See also REPOS.md and AGENTS.md.

Terminology

Term Meaning
Journal Elite Dangerous player log files (line-delimited JSON events), as consumed by local/remote readers in this ecosystem.
journalFilesSamples Optional workspace-local directory at repo root with real journal lines and sidecar JSON for schema verification — not published on the docs site; may be missing in partial clones. When docs and elite-dangerous-event-types are insufficient, agents ask the operator for samples — see AGENTS.md.
IPC (here) Mechanisms that connect host processes (native apps, shells) with embedded UIs (e.g. WebView, iframe), including postMessage and shared libraries dedicated to that. Not the same as OS-level IPC unless explicitly stated.
Host The application that owns the window or embeds web content (e.g. desktop shell loading a URL or local HTML).
Embedded UI / web app HTML/JS (or framework) running inside a WebView or browser surface, receiving or sending messages to the host.
Hosted app contract Portable rules for URL bootstrap (query/hash options), integration manifests (/.well-known/edos-integration.json), and optional embed handshakes—see HOSTED_APP_CONTRACT.md. Not the same document as IPC.md (MessageTypeEnum journal/file messaging).
App discovery registry Optional federated, link-only indexes that point at app origins and manifests for composition hosts—see APP_DISCOVERY_REGISTRY.md. Does not replace manifest-at-origin.
Community tooling Third-party Elite Dangerous tools that may embed or interoperate with these projects; compatibility targets (e.g. WebView2) are documented in architecture notes, not assumed here.
Community HTTP APIs Public HTTP services maintained by players (e.g. SPANSH, EDSM). Often no DDoS or rate-limit infrastructure; apps must use the API cache server (or equivalent) instead of calling those URLs directly — see ARCHITECTURE.md.
Visual identity Optional corporate design (CSS tokens, typography, layout habits) for first-party UIs — see DESIGN_GUIDANCE.md. Stack-agnostic; not a shared component library or runtime contract.
Third-party attribution User-visible link credits for integrated external APIs, assets, and frameworks — bottom center of hosted web UIs; required for first-party apps that use those integrations. See DESIGN_GUIDANCE.md — Third-party service attribution. Distinct from sourceUrl in versioned data files.

Use project when referring to a repo/folder; use app when emphasizing the user-facing deliverable (often the same boundary).

| Hostname / slug | Short ed* label and https://{slug}.howfe.org production host for deployable apps — see HOSTNAMES.md. |

File naming and layout

  • UPPERCASE.md for stable, top-level doc types: SCOPE.md, ARCHITECTURE.md, REPOS.md, HOSTED_APP_CONTRACT.md, APP_DISCOVERY_REGISTRY.md, AGENTS.md, etc.
  • **docs/apps/PROJECT_SLUG.md for per-project capsules (Phase 3), where PROJECT_SLUG matches the folder name** under the workspace root (e.g. elite-dangerous-surface-map.md).
  • **TODO.md** (optional): consolidated open documentation gaps; avoid scattering permanent TODO sections in multiple files without an index.
  • Prefer relative links between docs: [Architecture](./ARCHITECTURE.md).
  • When linking to code, use a path from the workspace root in backticks: elite-dangerous-surface-map/ui/src/... so it is searchable. If the doc repo is separate, state that code paths are relative to the code workspace checkout.
  • For external references (MDN, Frontier forums, etc.), use the full URL in markdown link form.

Diagrams

  • Use Mermaid in markdown where diagrams help (sequence, flow, simple graphs). Keep diagrams small; split into multiple figures rather than one unreadable chart.
  • Prefer one canonical system diagram in ARCHITECTURE.md (or equivalent); repeat only when a local diagram clarifies a subsection.

Uncertainty and facts

  • Documentation must not invent APIs, message shapes, or file paths. If behavior is not verified from code or existing authoritative notes, mark it explicitly: TODO: Verify — short hint where to look, e.g. TODO: Verify — message envelope in inter-frame-messenger (search postMessage).
  • Do not use TODO: Verify solely because a path is missing in a partial workspace checkout; open the full app repo or cite README/compose there.
  • When the source is known, prefer **path:line** (or a small line range) so agents can jump in the editor: See elite-dangerous-local-journal-reader/.../foo.ts:42 for tail implementation.
  • Do not leave vague TODOs (“check later”) without a next step (file, symbol, or grep hint).

Style for agent-oriented pages

  • Imperative checklists for procedures (“Before changing IPC, read …”).
  • Tables for contracts (message fields, env vars, CLI flags).
  • Short sections with clear ## headings; avoid walls of prose.
  • Scannable over literary: agents and humans both skim for anchors.

Curated data from other Elite Dangerous tools

EDOS does not import curated game data from other Elite Dangerous applications; use citable public references or verify and maintain the data in-repo.

This is an EDOS ecosystem boundary (other Elite Dangerous apps, plugins, and companion tools — including when their source is public). It does not define what other projects may do with software outside this ecosystem.

Allowed Not allowed
Open, citable references (wikis, published tables) with sourceUrl / attribution, transcribed into versioned in-repo data Another Elite Dangerous tool’s codebase, bundled files, plugin payloads, or scraped exports as the source of truth
Data from the game (journal events, in-game observations) with verification notes Crawling, copying, or porting curated tables/constants from another Elite Dangerous application

Community HTTP APIs (SPANSH, EDSM, etc.) are a separate contract: use the API cache — see ARCHITECTURE.md.

Exploration scan credit data (game payouts)

When EDOS projects implement exploration scan credit breakdowns (FSS, first discovery, DSS mapping, etc.):

Do Don't
Use open community references — primary matrix: Explorer § Scan Values on the Elite Dangerous Fandom wiki (CC-BY-SA; attribute sourceUrl in repo). Source payout matrices from other Elite Dangerous applications — see Curated data from other Elite Dangerous tools.
Transcribe tables into versioned JSON/TS in-repo with sourceUrl, wiki “as of” note, and lastVerified. Treat SPANSH estimated_scan_value / estimated_mapping_value as the canonical matrix (OK for sanity tests only).
Document wiki staleness and mark unverified star-type rows TODO: Verify. Invent undocumented constants without a cited open source.

See elite-dangerous-planet-analyser and apps/elite-dangerous-planet-analyser.md.

Relationship to original-concept.md

  • original-concept.md captures early postMessage / WebView considerations. New architecture docs may supersede or narrow that content; when they diverge, the newer doc should state that and point to the code that is authoritative.

Changelog

  • Doc-only changes are recorded in CHANGELOG.md. When the documentation moves to its own repo, keep that file at the docs root there.

Entry point