AGENTS.md

1# HASH Development Guide
2 
3## Repository Structure and Navigation
4 
5The HASH repository is organized into several key directories:
6 
7- `/apps` - Core applications powering HASH
8  - `/hash-api` - Backend API service
9  - `/hash-frontend` - Web frontend application
10  - `/hash-graph` - Graph database service
11  - `/hash-ai-worker-ts` - AI worker services
12  - `/hash-integration-worker` - Integration worker services
13 
14- `/infra/compose` - Docker Compose stack for external services (Postgres, Kratos, Hydra, Temporal, observability)
15 
16- `/blocks` - Block Protocol components (each subfolder contains a self-contained block)
17 
18- `/libs` - Shared libraries and packages
19  - `/@blockprotocol` - Block Protocol related libraries
20  - `/@hashintel` - HASH-specific libraries
21  - `/@local` - Internal libraries for the monorepo
22  - Other core libraries (e.g., `error-stack`)
23 
24- `/infra` - Deployment and infrastructure code
25  - `/docker` - Docker configurations
26  - `/terraform` - Terraform infrastructure as code
27 
28- `/tests` - Test suites spanning multiple components
29 
30**Navigation Tips:**
31 
32- When exploring a new feature, first identify which app or lib it belongs to
33- Related code is typically co-located within the same directory
34- Check existing implementations before creating new ones
35- For understanding cross-component interactions, look for integration tests in `/tests`
36 
37## Common Commands
38 
39### Development
40 
41- Main development: `yarn dev` (starts API and frontend)
42- Backend only: `yarn dev:backend` or `yarn dev:backend:api`
43- Frontend only: `yarn dev:frontend`
44 
45### Starting Services
46 
47- Start all services: `yarn start`
48- Start graph only: `yarn start:graph`
49- Start backend only: `yarn start:backend`
50- Start frontend only: `yarn start:frontend`
51- Start workers: `yarn start:worker`
52 
53### Testing
54 
55- Unit tests: `yarn test:unit`
56- Integration tests: `yarn test:integration`
57 
58### Linting and Fixing
59 
60- Lint everything: `yarn lint`
61- TypeScript type check: `yarn lint:tsc`
62- ESLint: `yarn lint:eslint`
63- Formatting check: `yarn lint:format`
64 
65- Fix ESLint issues: `yarn fix:eslint`
66- Fix formatting: `yarn fix:format`
67 
68### For Specific Packages
69 
70When working on a specific package, use:
71 
72```bash
73# For TypeScript/JavaScript packages
74turbo run &lt;command&gt; --filter '<package-name>'
75 
76# For Rust packages
77cargo nextest run --package &lt;package-name&gt;
78cargo test --package &lt;package-name&gt; --doc  # For doc tests
79cargo clippy --all-features --package &lt;package-name&gt;
80```
81 
82For Rust packages, you can add features as needed with `--all-features`, specific features like `--features=foo,bar`, or use `cargo-hack` with `--feature-powerset` for comprehensive feature testing.
83 
84### Monorepo wiring for Rust crates
85 
86Each Rust crate has a `package.json` whose **identity and workspace-dependency wiring** — its `@rust/<name>` name, version, and the `dependencies` mirroring its `Cargo.toml` — is generated from `Cargo.toml`. After **adding, removing, or renaming a Rust crate**, or changing its `Cargo.toml` dependencies, re-sync that wiring:
87 
88```bash
89mise run sync:turborepo    # sync package.json identity + deps from Cargo.toml metadata
90```
91 
92`sync:turborepo` only manages that generated wiring — the `scripts` section is hand-maintained and is used by CI and Turborepo (e.g. `test:unit`, `lint:clippy`, `doc:dependency-diagram`), so add or edit scripts by hand. The task wraps the `repo-chores` CLI; the equivalent direct invocation is `cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo`. A related task, `mise run fix:package-json`, sorts `package.json` keys consistently.
93 
94## Documentation Maintenance
95 
96### Petrinaut user-facing docs
97 
98The Petrinaut user guide lives at `libs/@hashintel/petrinaut/docs/*.md` and is the source of truth for end-user behaviour. The in-app AI assistant reads these pages at runtime via the `readPetrinautDoc` tool, so stale docs lead directly to wrong advice in the product.
99 
100When you change UI or behaviour in the petrinaut packages (`libs/@hashintel/petrinaut`, `libs/@hashintel/petrinaut-core`), you MUST:
101 
1021. Review the user-facing docs that mention the affected feature and update them in the same change.
1032. If you add a brand-new user-facing surface (panel, view, mode, tool, settings dialog, ...), add a corresponding page and link it from `libs/@hashintel/petrinaut/docs/README.md`.
1043. When you add a new doc page, also register it in `petrinautDocNames` and `petrinautDocSummaries` in `libs/@hashintel/petrinaut-core/src/ai.ts`, and add a `?raw` import in `libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts`. The tests in `libs/@hashintel/petrinaut-core/src/ai.test.ts` and `petrinaut-docs-content.test.ts` enforce that every enum value has a summary and a content entry.
1054. Keep the docs end-user-focused: describe what the user sees, what they click, what happens. Do not document Storybook, internal modules, or test setup in the user guide.
1065. If UI are changes that may make screenshots in the docs outdated, you MUST prompt your user to replace the screenshots.
107 
108If a change ships without doc updates, call that out in your summary so the user can decide whether to follow up.
109 
110## Contextual Rules
111 
112CRITICAL: For the files referenced below, use your Read tool to load it on a need-to-know basis, ONLY when relevant to the SPECIFIC task at hand:
113 
114- .config/agents/rules/\*.md
115 
116Instructions:
117 
118- Do NOT preemptively load all references - use lazy loading based on actual need
119- When loaded, treat content as mandatory instructions that override defaults
120- Follow references recursively when needed
121