Start here (new project / new agent)

Audience: Operator

This page is a bootstrap entry point you can copy into a new repo to kick off agent-based development with the same conventions used in the EDOS ecosystem.

If you are already inside the edos workspace, the main doc index is docs/README.md.

What is EDOS (in one minute)

• EDOS is a workspace of independent projects, not a monorepo.
• Projects integrate via:
• Journal event shapes from @howfe/elite-dangerous-event-types
• Browser IPC (window.postMessage) via @howfe/inter-frame-messenger
• Fair-use HTTP proxying of community APIs (SPANSH/EDSM/etc.) via api-cache-server
• Deployments are typically static UIs + a small cache service, all behind HTTPS.

If you’re working in the EDOS workspace

Use these as the “truth sources” before editing:

• Where to start: docs/README.md
• Scope: what belongs in docs and what doesn’t: SCOPE.md
• How the ecosystem connects: ARCHITECTURE.md
• IPC contract and origin rules: IPC.md
• Hosted app URL bootstrap and manifests (embedding vs journal postMessage): HOSTED_APP_CONTRACT.md
• App discovery registries (optional federated catalogs for composition hosts): APP_DISCOVERY_REGISTRY.md
• Agent checklists / guardrails: AGENTS.md
• Deployment model: DEPLOYMENT.md
• Inventory + run commands: REPOS.md
• Hostnames / acronyms for new deployable apps: HOSTNAMES.md

“Non-negotiables” to copy into new projects

1. Not a monorepo: keep your repo self-contained (its own package.json, CI, release cycle).
2. Do not call community APIs directly from browsers: route SPANSH/EDSM/etc. through the cache server (or an equivalent proxy with caching/queue behavior).
3. Keep IPC origin policy explicit: avoid '*' origin allowlists unless you document why.
4. Don’t invent contracts: if something isn’t verified in code/docs, mark it TODO: Verify with a concrete next step (file/symbol/search hint).

Quick references (copy/paste)

• Suggested reading order for agents (in this ecosystem):
• SCOPE.md
• REPOS.md
• ARCHITECTURE.md + IPC.md
• HOSTED_APP_CONTRACT.md when changing iframe entrypoints, query bootstrap, or integration manifests for hosted web UIs
• APP_DISCOVERY_REGISTRY.md when building composition hosts or registry indexes
• relevant capsule(s) under apps/

• AGENTS.md before making changes

• Deployment starting point:

• DEPLOYMENT.md
• AGENT_INDEX.md (compact machine-friendly entrypoint)

Template for a brand-new repo

Use the drop-in files under docs/templates/ in a local edos checkout (they are not published on docs.edos.howfe.org) as the first commit of a new project:

• docs/templates/PROJECT_START_README.md
• docker-compose for production (Traefik): docs/templates/compose.app.yml — reserve a slug in HOSTNAMES.md, then follow DEPLOYMENT.md

Hosted docs + empty Cursor folder

1. Publish the markdown doc tree (paths under docs/ as in this repo, e.g. README.md, DEPLOYMENT.md) behind HTTPS — static hosting is enough. The public /raw/ mirror matches that tree except docs/templates/ (repo-only).
2. From your checkout, open docs/templates/CURSOR_AGENT_BOOTSTRAP.md: it contains only the agent system prompt (rules + URLs with placeholder __EDOS_DOCS_BASE__).
3. If you use https://docs.edos.howfe.org, you can skip replacement and use docs/templates/CURSOR_AGENT_BOOTSTRAP_PROD.md directly.
4. Replace every __EDOS_DOCS_BASE__ with your public docs root without a trailing slash (production example: https://docs.edos.howfe.org). Hosted prompts use /raw/*.md for agent-friendly Markdown, not MkDocs HTML paths.
5. Copy that file into an empty folder for a new Cursor workspace. Optional: rename it to README.md only if you keep the first heading # EDOS — agent system prompt (hosted docs) (required for the global User Rule snippet in docs/templates/CURSOR_USER_RULE_GLOBAL_BOOTSTRAP.md, check 3).

Global Cursor User Rule (recommended): use one User rule everywhere so bootstrap loads without per-repo .cursor/rules. Conditional paths and paste instructions: docs/templates/CURSOR_USER_RULE_GLOBAL_BOOTSTRAP.md in the repo checkout.