Skip to main content

Open-source repo guide

This repository should be understandable without private context. It should also read like the open-source home of a real product, not just a scratchpad for people who already know the internals.

Documentation rules​

Good docs in this repo should:

  • use repo-relative commands like ./scripts/dev-up.sh
  • avoid personal machine paths such as /home/<user>/...
  • explain product surfaces first, then service boundaries
  • distinguish clearly between the hosted product story, the self-host path, and the Hermes runtime repo
  • include realistic verification commands, not just architecture prose

The public/default product URLs are:

For public-facing docs, use those by default unless the page is specifically about self-host bring-up or low-level validation.

Repo ownership​

This repo owns:

  • Synthien service implementations
  • shared contracts/protocol
  • deployment helpers
  • service-level smoke tests and stress harnesses
  • workspace/archive/commons flows

This repo does not own:

  • Hermes CLI UX as a product app
  • Hermes website copy except where runtime docs need clear repo-boundary links
  • private operator state or machine-specific workflows

Companion runtime repos​

Hermes is the main runtime that talks to Synthien. The intended repo split is:

  • NousResearch/hermes-agent is the upstream Hermes compatibility target.
  • synthien-dev/hermes-synthien is the canonical Synthien plugin/package for Hermes integration.
  • synthien-dev/hermes-agent is an optional integration fork while narrow Hermes-side extension points are missing or in review.

When docs need both service and runtime context:

  • runtime behavior belongs in Hermes or hermes-synthien docs
  • service behavior belongs here
  • integration examples can exist in both, but should say which side owns what

Suggested public docs set​

For this repo, the minimum useful public docs are:

  • hosted-first docs hub
  • quickstart
  • architecture overview
  • testing/stress guide
  • branding/service naming
  • memory/workspace/commons behavior docs

PR stack docs​

For Hermes mesh-related work, the docs/prs/ files in the Hermes repo should help open-source reviewers understand:

  • why the PR exists
  • what files it touches
  • what commit stack is suggested
  • what test command proves the slice