agents/ and vault/ copy the frontend packages they use through file: dependencies, so a change to frontend/packages/* reaches them only after bun install. Their dev servers re-sync automatically. The map pages under The Seed software, such as Daemon, Desktop and Web, explain how the programs talk to each other.

The toolchain versions are pinned in mise.toml and activated by direnv.

Install mise and direnv and hook direnv into your shell, then clone the repository and allow the environment. The first direnv allow installs the pinned tools, initializes the llama-go submodule, downloads the embedding model and builds the llama.cpp libraries, which takes a few minutes.

Install Docker as well if you want the full stack, because the agents' web search backends run as containers.

./dev refuses to run outside a direnv-enabled shell. From scripts and agents, run commands as direnv exec . <command>.

./dev with no arguments lists every command. The ones you will use:

./dev up starts these panes:

In mprocs, r restarts the focused process, s stops it, x starts it and q quits everything. Quitting also runs docker compose down for the search containers. The development daemon uses ports 58000 to 58004. The full port table is on Network.

Root package.json scripts start single apps: pnpm web, pnpm desktop, pnpm notify, pnpm explore, pnpm mobile, and pnpm web:standalone, which runs a web app against its own daemon.

Run the checks for every area you touched. CI runs the same ones, and a single unformatted file anywhere fails the Lint job.

In agents/ and vault/, bun check runs the type checker and rewrites formatting, so commit whatever it changes. Go tests need the submodule and model that direnv allow fetched. CI runs them with go test -tags cpu --count 1 ./backend/.... For backend bug fixes, add a failing test first when practical, and use testify/require in Go tests.

To reproduce CI locally before pushing, use agent-ci. docs/local-ci-with-agent-ci.md has the guide.

Storage schema and migrations

Protobuf and generated code

Protocol changes

Deployment tooling

Maintainers cut releases with the runbook in docs/releasing.md.

Pick the version YYYY.M.N: the year, the month without zero padding, and the next number within the month. Check recent tags with git tag --sort=-creatordate | head -5.

Tag the release commit, normally the tip of main, and push the tag. A *.*.* tag starts the Release - Desktop App and Release - Docker Images workflows.

Wait for the desktop workflow to build every platform and create the GitHub release as a prerelease.

Write short, user-facing release notes with Features and Bug Fixes sections and a full-changelog link, then publish them with gh release edit <tag> --notes-file <file> --prerelease=false --latest.

Run the Generate latest.json (prod) workflow so desktop auto-update sees the new version.

Two packages publish on their own. Pushes to main that touch the SDK or the CLI run the publish-client workflow, so there is no manual npm step.

This site is the hypermedia/ folder, and a commit to main publishes it through .github/workflows/sync-hypermedia.yml. Pages are plain markdown with a name and a one-sentence summary in the frontmatter. Links between pages are relative .md links. The dialect round-trips losslessly through the Seed app. hypermedia/README.md explains the layout, and Publish a folder explains the round trip.

Rules that matter when you edit:

Nothing publishes while any relative link is broken, so fix links in the same commit that moves a page.

Renaming a file in git publishes a move with a redirect at the old address.

Deleting a file retires its document on the next push, unless the push runs with --keep-stale.

A page with a *.schema.json beside it defines a schema. Keep its path, and let check.mjs confirm the lockfile and generated types.

Keep the <!-- id:… --> comments on lines you keep. They are block ids. New pages need none.

Corrections are welcome as pull requests, or as comments on the published page.

Report security issues by email to security@hyper.media. Do not open a public issue or pull request about an unfixed vulnerability. This repository is public.

Once a vulnerability is fixed, the team discloses it as a GitHub issue closed by the fixing commit. The public record of what has been audited and which hypotheses were ruled out is docs/security/audit-log.md, and the audit procedure itself is docs/security/auditor.md. The known limits you should design around, such as the unauthenticated local daemon API and non-revocable capabilities, are listed on Integrity.