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
• Agent checklists / guardrails: AGENTS.md
• Deployment model: DEPLOYMENT.md
• Inventory + run commands: REPOS.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
• 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 this drop-in template as the first commit of a new project:

• docs/templates/PROJECT_START_README.md
• docker-compose for production (Traefik): docs/templates/compose.app.yml - full checklist in DEPLOYMENT.md

Hosted docs + empty Cursor folder

1. Publish the markdown doc tree (same paths as under docs/ in this repo, e.g. README.md, DEPLOYMENT.md) behind HTTPS — static hosting is enough.
2. 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 global User Rule snippet, 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: CURSOR_USER_RULE_GLOBAL_BOOTSTRAP.md.