docs(repo): add contributor orientation guides

.claude/commands/push.md

@@ -3,20 +3,15 @@ name: push
 description: Run pre-push checks including typecheck and tests
 ---
 
-Run the following pre-push checks to ensure code quality before pushing to remote:
+Run pre-push checks before pushing to remote:
 
-1. **Type checking**: Run `yarn typecheck` to check for TypeScript errors
-2. if you find any errors. fix them.
-3. comment this lines in "dev" file:
-```
-run("node scripts/cleanup-desktop.js")
-run("./scripts/cleanup-frontend.sh")
-```
-4. **Tests**: Run `./dev build-desktop && yarn web:prod` to ensure the apps build properly and tests pass
-5. uncomment the lines in the "dev" file.
-6. if there are any changes you made to fix the typecheck, commit with `--amend` the changes keeping the same message code. no need to change the commit message, just add the new changed files.
-7. git pull
-8. git push
-9.  **Report results**: Provide a summary of which checks passed or failed
+1. **Type checking**: run `pnpm typecheck` from the repo root.
+2. **Tests**: run `pnpm test` from the repo root.
+3. **Build smoke checks**: run `./dev build-desktop` and `pnpm web:prod` when the changed files can affect desktop or
+   web builds.
+4. **Formatting**: run `pnpm format:write` if the checks or edits touched formatted files.
+5. If a check fails, fix it in place and rerun the failed command.
+6. Report which checks passed or failed and include any remaining errors.
 
-If any checks fails and you cannot fix it, describe that in the report, provide details about the errors so they can be fixed before pushing.
+Do not edit `dev` just to run these checks. Do not amend, pull, or push unless the user explicitly asked for git
+changes.

.cursor/rules/web.mdc

@@ -1,14 +1,19 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
-This mostly includes details about `frontend/apps/web`
+
+This mostly includes details about `frontend/apps/web`.
 
 # Tests
 
-Run tests for things in the `frontend/apps/web`, if there is a test file present. Do this automatically without me asking you!
+Run tests for things in `frontend/apps/web` automatically when there is a relevant test file.
+
+Use pnpm from the repo root:
 
-Run the tests by running `yarn web:test run <testFileName>` in the repo root. If you forget to include `run`, you will be stuck in watch mode! Orjust `yarn web:test run` to run all web test. Also you can run `yarn workspace @shm/shared test run` for tests in `frontend/packages/shared`
+- `pnpm --filter @shm/web test -- <testFileName>` for one web test file.
+- `pnpm web:test` for all web tests.
+- `pnpm --filter @shm/shared test -- <testFileName>` for relevant shared package tests.
 
-If you are working on something that is easily tested, you can offer to create a test
+If you are working on something that is easily tested, offer to create or update a test.

AGENTS.md

@@ -28,6 +28,8 @@
 
 ## Workflow
 
+- For cross-subsystem work, read `docs/README.md`, `docs/code-map.md`, and the relevant glossary or architecture doc
+  before planning or making changes.
 - Ask clarifying questions when ambiguity matters.
 - Use OS temp dir for scratch files. Clean up after you're done.
 - Ask for elevated permissions instead of working around sandboxing issues (if you can run in a sandbox).

README.md

@@ -1,15 +1,13 @@
 # Seed
 
-Seed is a decentralized knowledge collaboration application for open
-communities powered by a knowledge graph.
+Seed is a decentralized knowledge collaboration application for open communities powered by a knowledge graph.
 
 You can read more about the product and why we are here on our website: https://seed.hyper.media.
 
 ### Hypermedia Protocol
 
-Seed Hypermedia is powered by the new [Hypermedia Web Protocol](https://hyper.media). This
-open protocol provides secure identities, version control, semantic documents, multimedia,
-and groups/organizations.
+Seed Hypermedia is powered by the new [Hypermedia Web Protocol](https://hyper.media). This open protocol provides secure
+identities, version control, semantic documents, multimedia, and groups/organizations.
 
 ### Desktop App + Web Server
 
@@ -20,32 +18,39 @@ This repo includes:
 
 ## ⚠️ Stability
 
-This is software is being actively developed, and may contain bugs and rough edges.
-We appreciate any feedback and bug reports, so if you find any, please open an issue.
+This is software is being actively developed, and may contain bugs and rough edges. We appreciate any feedback and bug
+reports, so if you find any, please open an issue.
 
-The permanent data format has been declared stable, and we don't expect any breaking changes there.
-Documentation is still missing though, but it will come.
+The permanent data format has been declared stable, and we don't expect any breaking changes there. Documentation is
+still missing though, but it will come.
 
-We still recommend you to have a copy of anything valuable you put into the app, while we are polishing it,
-and improving the overall stability.
+We still recommend you to have a copy of anything valuable you put into the app, while we are polishing it, and
+improving the overall stability.
 
 ## Dev Environment
 
-See the [developer setup](./docs/docs/dev-setup.md) page for detailed instructions.
+See the [developer setup](./docs/dev-setup.md) page for detailed instructions.
 
-The dev environment on macOS+Linux uses the [Mise](https://mise.jdx.dev),
-and [Direnv](https://direnv.net).
+## Contributor orientation
 
-The bare minimum required for compilation is to have Go, and NodeJS toolchains
-installed.
+Start with the [Seed Builder Guide](./docs/README.md) when building or fixing across subsystems. Useful entry points:
+
+- [Domain glossary](./docs/domain/glossary.md) for account/key/vault/document/resource terminology.
+- [Architecture overview](./docs/architecture/overview.md) for runtime boundaries and sources of truth.
+- [Code map](./docs/code-map.md) for "if touching X, start here" file lists.
+- [Frontend map](./frontend/README.md) and [backend map](./backend/README.md) for subsystem-specific orientation.
+
+The dev environment on macOS+Linux uses the [Mise](https://mise.jdx.dev), and [Direnv](https://direnv.net).
+
+The bare minimum required for compilation is to have Go, and NodeJS toolchains installed.
 
 [./dev](./dev) is the main dev CLI. Run `./dev` to list commands, including:
 
 - `./dev run-desktop`
 - `./dev run-desktop-mainnet`
 - `./dev build-desktop`
-- `./dev run-site`
-- `./dev build-site`
+- `./dev run-web`
+- `./dev build-web`
 
 To run the dev build with the production network, use the following command:
 
@@ -58,22 +63,20 @@ SEED_P2P_TESTNET_NAME="" ./dev run-desktop
 ```bash
 pnpm test               # test all the packages
 pnpm desktop:test       # test desktop app (e2e only now)
-pnpm site:test          # test only site code (WIP)
+pnpm web:test           # test only web app code
 ```
 
 ## Web Build
 
 ## Group sites
 
-Group sites need two programs to run. The daemon which includes the P2P node (go app)
-and the frontend that renders documents (nextjs app). However for a production
-deployment everything is orchestrated by docker compose. Read next sections for how to
-either deploy a site on a production server or run it locally in dev mode
+Group sites need two programs to run. The daemon which includes the P2P node (go app) and the frontend that renders
+documents (Remix app). However for a production deployment everything is orchestrated by docker compose. Read next
+sections for how to either deploy a site on a production server or run it locally in dev mode
 
 ### Deploy a Group Site
 
-To deploy a group into a site, make sure you have a domain name and
-a server with the following requirements:
+To deploy a group into a site, make sure you have a domain name and a server with the following requirements:
 
 1. At least 2GB RAM
 2. Al least 512MB free space in root partition.
@@ -85,35 +88,33 @@ After checking that, run the following command in the server:
 sh <(curl -sL https://raw.githubusercontent.com/seed-hypermedia/seed/main/website_deployment.sh) https://example.com
 ```
 
-replacing `https://example.com` by your <`address`> If everything went well,
-after some seconds, you should be watching a final output line like
-`https://example.com/secret-invite/XXXX`. You should paste that link back into
-the owner's application to register the newly created site and start publihing.
-The site deployment workspace will default to `~/.seed-site`.
+replacing `https://example.com` by your <`address`> If everything went well, after some seconds, you should be watching
+a final output line like `https://example.com/secret-invite/XXXX`. You should paste that link back into the owner's
+application to register the newly created site and start publishing. The site deployment workspace will default to
+`~/.seed-site`.
 
 #### Auto-Update a Site
 
-If you want the site to auto update to latest stable images when they are pushed,
-just execute the installation command with the `--auto-update` flag. Ex:
+If you want the site to auto update to latest stable images when they are pushed, just execute the installation command
+with the `--auto-update` flag. Ex:
 
 ```shell
 sh <(curl -sL https://raw.githubusercontent.com/seed-hypermedia/seed/main/website_deployment.sh) https://example.com --auto-update
 ```
 
 #### Replace Site
 
-If you want to replace an old site with a new site in a different domain in the same machine,
-you need to redeploy the site from scratch. Note that old content will be available as long as
-the owner of the site is synced with the site at the moment of the replacement. On the server:
+If you want to replace an old site with a new site in a different domain in the same machine, you need to redeploy the
+site from scratch. Note that old content will be available as long as the owner of the site is synced with the site at
+the moment of the replacement. On the server:
 
 ```shell
 docker stop seed-web
 mv ~/.seed-site ~/.seed-site.bak
 docker start seed-web
 ```
 
-Get the new secret link from the command line after starting the `seed-web` container
-Now in the Seed App, the Owner of the site can go to the group he/she wants to (re)deploy
-and click on the three dots, and publish group to site. Enter the new secret and the old content
-should be now available in the new site. If there is no new content (A completely new group), then
-the site will be empty ready to accept documents
+Get the new secret link from the command line after starting the `seed-web` container Now in the Seed App, the Owner of
+the site can go to the group he/she wants to (re)deploy and click on the three dots, and publish group to site. Enter
+the new secret and the old content should be now available in the new site. If there is no new content (A completely new
+group), then the site will be empty ready to accept documents

backend/README.md

@@ -0,0 +1,47 @@
+# Backend
+
+Status: current.
+
+The backend is the Go runtime for Seed. It contains the daemon, API implementations, blob formats/indexing, SQLite
+storage, P2P networking, and backend tests.
+
+## Package map
+
+| Path                                               | Ownership                                                                                                                              |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [`api`](./api)                                     | gRPC service implementations and API test helpers. Mirrors `proto/**` service areas.                                                   |
+| [`api/documents/v3alpha`](./api/documents/v3alpha) | Documents, resources, comments, contacts, access control, document history.                                                            |
+| [`api/entities/v1alpha`](./api/entities/v1alpha)   | Entity timeline, search, delete/undelete, discovery entry points.                                                                      |
+| [`api/activity/v1alpha`](./api/activity/v1alpha)   | Activity feed and subscription APIs.                                                                                                   |
+| [`api/daemon/v1alpha`](./api/daemon/v1alpha)       | Daemon admin/key/vault/domain APIs.                                                                                                    |
+| [`blob`](./blob)                                   | Signed blob formats (`Change`, `Ref`, `Comment`, `Capability`, profile/contact), blob store/indexing, visibility propagation.          |
+| [`storage`](./storage)                             | SQLite store, schema source of truth, migrations, local vault storage. Read [`storage/AGENTS.md`](./storage/AGENTS.md) before editing. |
+| [`hmnet`](./hmnet)                                 | libp2p node, Bitswap/file serving, peer/debug endpoints, P2P client/server plumbing.                                                   |
+| [`hmnet/syncing`](./hmnet/syncing)                 | Authorized sync, discovery, scheduling, sync server.                                                                                   |
+| [`daemon`](./daemon)                               | App composition: storage, index, network, sync, gRPC, HTTP, metrics, reindexing, LLM embedding.                                        |
+| [`cmd/seed-daemon`](./cmd/seed-daemon)             | CLI entry point for the daemon binary.                                                                                                 |
+| [`core`](./core)                                   | Cryptography, principals, key pairs, keystores, mnemonics.                                                                             |
+| [`config`](./config)                               | Daemon configuration and defaults.                                                                                                     |
+| [`llm`](./llm)                                     | Embedding backends and llama.cpp/Ollama integration.                                                                                   |
+| [`util`](./util)                                   | Shared Go utilities; keep new helpers small and justified.                                                                             |
+
+## Sources of truth
+
+- Proto contracts: [`../proto`](../proto).
+- DB schema: [`storage/schema.sql`](./storage/schema.sql).
+- DB migrations: [`storage/storage_migrations.go`](./storage/storage_migrations.go).
+- Blob formats: [`blob/blob_*.go`](./blob).
+- Daemon composition: [`daemon/daemon.go`](./daemon/daemon.go).
+
+## Common commands
+
+```bash
+go test ./backend/...
+golangci-lint run --new-from-merge-base origin/main ./backend/...
+go install ./backend/...           # compile-only check
+./dev run-backend -- -http.port=53001 -grpc.port=53002 -p2p.port=53000
+./dev gen //backend/...             # after generated schema/proto-affecting changes
+```
+
+For local CI parity before pushing, use the backend workflows from
+[`../docs/local-ci-with-agent-ci.md`](../docs/local-ci-with-agent-ci.md).