# AGENTS.md Read this top to bottom before writing any code. ## What is this project? Read `README.md` (one page). It explains the product, where the idea comes from, and the MCP-first loop. The deployment model is in the install guide on nexul.io, and the standing principles are at the end of `ROADMAP.md`. The product is implemented. The work now is improving it domain by domain. ## How to navigate the docs | You are doing | Read first | Then read | |---|---|---| | Anything | `CONTEXT.md` (the vocabulary) | `docs/adr/` for the decisions in your area | | Picking up work | `.scratch/`, the issue tracker | `docs/agents/issue-tracker.md` for its conventions | | Go backend | `practices/go.md` | `practices/architecture.md` | | Frontend (React) | `practices/react-guide.md`, the F1 to F7 commandments are enforced | `practices/design-language.md`, the shared core and the web app section | | SDK, automations host, desktop | `practices/typescript.md` | `practices/react-guide.md` for the desktop launcher | | Phone app (React Native) | `practices/native.md` | `practices/react-guide.md`, the rules it inherits; `practices/design-language.md`, the shared core and the phone app section | | Code both the web and phone apps run (`client-core/`) | `practices/typescript.md`, section 11 | ADR 0139 | | Design or visual work in `web/`, `website/` or `native/` | `practices/design-language.md`, one language for all three: the shared core, then your surface's section | `practices/react-guide.md`, or `practices/native.md` on the phone | | Testing, or making something faster | `practices/testing.md` | The language file above | | Any code | `practices/architecture.md`, Principles | `practices/README.md` for the index | | Install, CI, release | [CI and releases](https://nexul.io/docs/contributing/ci-and-releases/) | `internal/install/`, `.goreleaser.yaml`, `docker-compose.debug.yml` for development | | MCP server or a domain's `mcp.go` | `practices/mcp.md` | `practices/architecture.md`, section 8 | | A list call: an MCP list tool or a paged endpoint | `practices/go.md`, section 17 | `practices/mcp.md`, section 7; ADR 0140 | | Event bus or resilience | `practices/architecture.md`, sections 2 to 6 | `docs/adr/` | | Why is it built this way? | `docs/adr/` | The effort's spec in `.scratch/` | | Unfamiliar with a term | `CONTEXT.md` | (the ubiquitous language) | The practices files are the standard. The contributing pages on nexul.io are a digest derived from them, never the other way round. ## Agent skills This repo is configured for the mattpocock/skills engineering set. Issues and specs live as markdown under `.scratch//`, committed to the repo. See `docs/agents/issue-tracker.md`. The five triage labels are `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`. `CONTEXT.md` is the glossary, `docs/adr/` is the decision log, and the tracker holds the specs. See `docs/agents/domain.md`. `.scratch/pre-release/` holds deferred concerns, each with a "Surface when" list. If a trigger matches the current task, raise it with the owner before implementing. Never act on one silently. ## The hard rules These override everything else. If a practices file says something different, these win. 1. Read the practices before writing code, every session. The navigation table above is a gate, not a suggestion. Before the first edit, read the `practices/` files matching the work. Delegated work inherits this: any brief that involves writing code names the files to read before editing, and they get read there. A summary in the brief does not count. 2. MCP-first, not MCP-only. The browser uses the HTTP/JSON gateway. The MCP server is for LLMs. Both are adapters over the same use-case layer, which is the single source of behavior. 3. SQLite is the spine. One file, one owner, WAL mode, FTS5. No Postgres. No dual-backend abstraction. Semantic search deferred. 4. The EventBus interface is the microservice seam. Domains communicate only through it. Today it is in-process channels; a broker adapter can replace it without touching a domain. 5. Coverage is a floor (80%), not a goal. Test error paths first. Exempt: `cmd/*`, generated code, wire types, `testutil/`, `t3rpctest/`, `components/ui/`. 6. No barrels. No `index.ts` re-exports. Import by full path. 7. Early return, no `else`, in Go and TypeScript alike. 8. Structured logging: `slog` in Go, console with a propagated `trace_id` in TypeScript. No `fmt.Println`, no `console.log` in production code. 9. Comments are sparse. The default is no comment; the code and its names carry the meaning. A comment exists only to say a why, a warning about a non-local consequence, or a pointer to context, and it fits on one line. Knowledge that needs more than one line is an ADR if it is a decision, otherwise it belongs in the tracker spec for the work. No comment restates the code. No change history ("previously", "per PR"). No commented-out code. No TODO without a tracking issue in `.scratch/`. 10. Web work obeys the Frontend Commandments. F1 to F7 in `practices/react-guide.md` are hard rules for anything in `web/`: Page, Feed, Section, Card; defensive ordering; shared display components; `&&` over ternary; no gratuitous `useState` or `useEffect`; no prop drilling; thin files. Implement against the rule, not against nearby code that predates it. Run the self-review checklist before calling web work done. 11. One design language across `web/`, `website/` and `native/`; extend it, never re-theme. `practices/design-language.md` is the spec for all three, and a screen that disagrees with it is the defect. Tokens only, no one-off colours: the one accent is `brand`, held to the roles the spec names, and status keeps its own hues. Fraunces is the one serif, for display headlines only; no script fonts. The three token files (`web/src/index.css`, `website/src/styles/tokens.css`, `native/src/global.css`) carry the same names and values; a design that needs a missing token adds it to each surface that uses it and to the token table in `practices/design-language.md`, never as a one-off class. 12. Tablet and desktop. Build `web/` at 768px first and verify at 768, 1024, and 1440px before calling web work done; phones are served by the Android app in `native/` (ADR 0080). `website/` stays mobile first: build at 320, 375, and 414px and verify at 320, 375, 414, and 768px. 13. Fast by default, and kept fast by a test. Lists page and filter by access in SQL, a client refreshes only what a frame names, and a background loop waits on the commit broadcast instead of polling. A performance fix ships with a before and after number from a production build and a guard test that counts something deterministic (`practices/testing.md`, section 10). ## What enforces the rules A rule a linter can check is checked by a linter, because prose rules get skipped and lint errors do not. | Rule | Gate | |---|---| | Early return after a return, no `else if` chains, no `fmt.Print` outside `cmd/` (Go) | `revive` (`indent-error-flow`, `superfluous-else`, `early-return`), `gocritic` (`ifElseChain`, `elseif`) and `forbidigo` in `.golangci.yml`; an `else` after a branch that does not return is not caught, so review it | | No `else` and no `console.log` in TypeScript | `no-restricted-syntax` (`IfStatement[alternate]`) and `no-console` (`warn` and `error` allowed; tests exempt) in `web/eslint.config.js` (covers `client-core/`) and `native/eslint.config.js` | | Go static analysis, formatting, imports, complexity | `golangci-lint` with `.golangci.yml`, in CI and `make lint` | | Known-vulnerable Go dependencies | `govulncheck`, in CI and `make vuln` | | Go coverage floor | `make coverage`, in CI and locally | | Generated SQL code matches the queries | `sqlc vet` and `sqlc diff`, in CI and `make sqlc-check` | | Web lint, types, tests, coverage | `bun run lint`, `typecheck`, `test` in `web/`, in CI | | Native lint, types, tests | `bun run lint`, `typecheck`, `test` in `native/`, in CI | | SDK and automations host types and tests | `bun run typecheck` and `bun run test` in each package, in CI | | Desktop types, tests, build | the desktop CI job | | Every pushed topic has an audience rule, and the topics the server pushes match the ones the web followers follow | `make live-topics`, `TestLiveRules_MatchWhatIsPushed`, `TestLiveTopicsFile_MatchesTheRules` and `web/src/hooks/liveTopics.test.tsx` | | The clients' typed permission list matches the server's catalog | `make permission-catalog` and `TestPermissionActionsFile_MatchesTheCatalog` in `internal/platform/permissions` | | Every writing route names the permission it checks, and every web and phone write declares one the route accepts | `make permission-catalog`, `TestRoutePermissions_NameEveryWritingRouteAndOnlyCatalogActions` and `TestRoutePermissionsFile_MatchesTheRoutes` in `server/cmd`, and `client-core/routePermissions.test.ts` | | Event schemas match the payload types and the published contract only grows | `make event-schemas`, `TestSchemas_MatchThePublishedContract` in `internal/eventcatalog/contract_test.go` | | HTTP bodies through `jsonx` match the encoder it replaced | `server/cmd/json_parity_test.go` | | An event payload's empty list is `[]`, never `null` | the contract test above, and `TestInsertOutboxRow_WritesAnEmptyListAsAnArray` | | A memoised access check answers what an unmemoised one does, and a commit clears it | `TestIntegration_PermissionSuitesAnswerTheSameWithAMemo` and `TestIntegration_LiveAudienceMemo_FollowsEveryChange` in `server/cmd/access_memo_test.go` | | A list path's access reads stay the same at any length | the `TestStatements_*` guards in `server/cmd/access_memo_test.go` | | A background loop wakes on a write to every table its pass reads, and on no other | `TestLoopWrites_CoverEveryTableTheLoopsPassReads` and `TestStore_CommitsTo_AMachineTouchWakesNoLoopButTheMemo` in `internal/platform/storage` | | A paged list tool shows each viewer what the row-by-row check showed, and reads about one page of rows | `TestListTools_ShowWhatTheRowByRowCheckShowed` and the `TestRows_*` guards in `server/cmd/list_paging_test.go` | | Every non-GET route writes an audit row unless it is listed as read-only | `TestAudited_EveryRouteOfTheRouter_IsClassifiedByMethod` in `server/cmd/audit_integration_test.go` | | No goroutine outlives a package's tests | `goleak.VerifyTestMain` in each goroutine-owning package's `main_test.go` | | The web shell loads no page, editor, canvas, voice or shader | `web/src/pageChunks.test.tsx` | | A gated page's chunk loads only for a viewer who may open it | the gated page chunks cases in `web/src/RouterPermissions.test.tsx` | | Requests one live frame or one phone session sends | `web/src/hooks/liveRequests.test.tsx`, `native/src/hooks/requestCounts.test.tsx` | | `client-core/` lint, tests and coverage | the web job: `bun run lint` covers the folder, and vitest runs its tests and counts its code toward the 80% gate; each app's typecheck compiles what it imports | | A phone query cached until pushed names a topic, and its topics and payload fields exist in the catalog | `bun run typecheck` in `native/`, through the `@ts-expect-error` cases in `native/src/lib/liveQuery.test.ts` | | A catalog topic reaches exactly the phone queries that declare it | the per-topic table test in `native/src/hooks/useLiveEvents.test.tsx` | | Phone icons import by path; the SDK's event types import as types only | `no-restricted-imports` in `native/eslint.config.js` | | Web text sizes come from the type scale, and no component writes its own focus ring | `no-restricted-syntax` in `web/eslint.config.js` | | Dependency freshness | Dependabot, weekly, grouped per directory | A rule that could be a lint rule and is not yet is a candidate for one; add it to the tracker rather than repeating it in review. ## Hit every surface The most common defect in this repo is a change that works on the path you tested and is missing everywhere else. Before calling a feature done, walk this list and say which entries applied: - UI page or component. The browser flow works at 768, 1024, and 1440px. - HTTP gateway route. The browser and integrations reach it (ADR 0019). - MCP tool. Agents are peers of the browser; a capability without a tool is half shipped. A list tool pages in SQL through its use-case, filters by access in the query, and joins the parity and row guards in `server/cmd/list_paging_test.go` (`practices/go.md`, section 17). - Events. A `Topics()` entry naming the payload type, `make event-schemas`, and an outbox write, designed for publication (ADR 0044, ADR 0137). A new field goes beside the existing ones, never in place of one, and is followed by `make event-schemas`. A client that refreshes too much because a frame lacks an id is fixed by adding that id this way. - Live WebSocket push, if the UI should update without a refresh. A new topic gets an audience rule in `liveRules` (that bridges it), `make live-topics`, a follower in the web domain's hooks file (`practices/react-guide.md`, The live topic contract), and a line in the `refreshes` of each phone query that shows the entity (`practices/native.md`, section 4). - Both apps. Code the web and the phone app both need lives once in `client-core/`, with its tests beside it (`practices/typescript.md`, section 11); each app keeps only its adapter. - Search, if the entity is indexed. - Permissions. Enforced through the permission table, not assumed. - Reverse states. If you added a way in, add the way out and the way to see it. Archive needs restore, close needs reopen. A one-way door is a bug. - Docs. Check whether the change makes an ADR, `CONTEXT.md`, or a practices file inaccurate, and fix it in the same change. - User guide. A feature added or changed updates its page under `website/src/content/docs/docs/guide/` in the same change, or adds one. ## Plans and work artifacts - Do not commit implementation plans, research notes, audit reports, or agent scratch files. Temporary working material lives outside the tree or in a path listed in `.git/info/exclude`. - `.scratch/` holds specs and tickets for open efforts, nothing else. When an effort ships, its directory is deleted. - A merged PR is the implementation record. Close its ticket when the work lands; do not keep a second checklist anywhere in the repository. - Nothing shipped names the tool that wrote it. Commit messages, PR bodies, comments, and docs describe the change from the code's point of view. ## Branches and pull requests Parallel work happens in worktrees (`git worktree add ../nexul- -b `). Things the commands do not tell you: - Remove the worktree when the branch is done; each one is about 65MB. - Parallel runs share this host. Give each its own dev-server port and say so up front, or they collide on the default port and the screenshots come back belonging to somebody else's container. - Kill only a PID you captured at spawn, never by pattern (`pkill -f`, `pgrep | kill`): your own session matches the pattern. A pull request: - Carries one topic. A description that says "also" is two pull requests. - Is rebased onto the latest `master` before it opens, so the diff is only the change. - Is squash-merged. Its title is one sentence describing the change from the code's point of view, because that sentence becomes the commit on `master` and the line in the release notes. - States the problem in a sentence or two, then how the change fixes it. A UI change carries before and after screenshots at 768, 1024, and 1440px (320, 375, 414, and 768px for `website/`); a change that depends on motion carries a short video. - Never commits a secret. A dev-only shared value is tracked as an open item in `.scratch/pre-release/` until it is rotated. CI runs per service through `dorny/paths-filter`, so only the affected service's jobs run. ## Code discovery `rg` is the default and is never stale. Reach for the `codebase-memory-mcp` server only for structural questions it answers better: `trace_path` for who calls what, `search_graph` to disambiguate an overloaded name. Reindex (`index_repository`) before tracing if files moved, not after every new file. ## Quick reference: adding a new domain 1. Create `internal//` with `model.go`, `repo.go`, `usecase.go`, `handler.go`, `events.go`, and `mcp.go` if it exposes tools. 2. Add the repo implementation in `internal/platform/storage/`, with the queries in `internal/platform/storage/queries/.sql` and `make sqlc`. 3. Register the domain's topics with their payload types in its `Topics()` function and run `make event-schemas`; the catalog aggregates them (`practices/architecture.md`, section 2). 4. Expose the use-cases to agents per `practices/mcp.md`: extend an existing tool first, add one only inside the tool budget, named `