H-2798: Update developer-facing docs and fix broken links (#4538)

Co-authored-by: Tim Diekmann <[email protected]>

.github/CONTRIBUTING.md

@@ -1,39 +1,51 @@
+[careers site]: https://hash.ai/careers?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[community guidelines]: https://hash.ai/legal/trust-safety/community?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[discord]: https://hash.dev/discord?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[discussion]: https://github.com/hashintel/hash/discussions
+[hash.design]: https://hash.design/?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[hash.dev]: https://hash.dev/?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[issue]: https://github.com/hashintel/hash/issues
+[our commitment as a company]: https://hash.dev/blog/open-source?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[public roadmap]: https://hash.dev/roadmap?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[tell us about yourself]: https://hash.ai/contact?topic=careers&category=applying&utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+[why we have a cla]: https://hash.ai/legal/developers/contributing?utm_medium=organic&utm_source=github_readme_hash-repo_community-file
+
 # Contributing
 
-Thanks for taking the time to contribute! 🎉 We've established a set of [community guidelines](https://hash.ai/legal/community) to enable as many people as possible to contribute to and benefit from HASH. Please follow these when interacting with this repo.
+Thanks for taking the time to contribute! 🎉 We've established a set of [community guidelines] to enable as many people as possible to contribute to and benefit from HASH. Please follow these when interacting with this repo.
 
-If you'd like to make a significant change or re-architecture to this repository or any project within, please first open a [discussion](https://github.com/hashintel/hash/discussions) or create an [issue](https://github.com/hashintel/hash/issues) to get feedback before spending too much time.
+If you'd like to make a significant change or re-architecture to this repository or any project within, please first open a [discussion] or create an [issue] to get feedback before spending too much time.
 
 We also have:
 
-- A community [Discord server](https://hash.ai/discord) where you can ask questions about contributing, and obtain helpful advice
-- A developer website at [hash.dev](https://hash.dev/), containing developer tutorials, guides and other resources
-- A design website at [hash.design](https://hash.design/) containing our Storybook, brand and style guildelines
+- A community [Discord] server where you can ask questions about contributing, and obtain helpful advice
+- A developer website at [hash.dev], containing developer tutorials, guides and other resources
+- A design website at [hash.design] containing our Storybook, brand and style guildelines
 
 ## About this repo
 
-This repository is HASH's public monorepo. It contains [many different](README.md) projects, the vast majority of which are open-source, in line with [our commitment as a company](https://hash.dev/blog/open-source). While each project has its own [license](LICENSE.md), our contribution policies are consistent across this whole repository.
+This repository is HASH's public monorepo. It contains [many different](README.md) projects, the vast majority of which are open-source, in line with [our commitment as a company]. While each project has its own [license](LICENSE.md), our contribution policies are consistent across this whole repository.
 
 To ascertain the license and contributing policy for any given project, check out the `LICENSE.md` and `CONTRIBUTING.md` files in its root.
 
 ## Common contribution processes
 
 These apply across all projects:
 
-- Before undertaking any significant work, please share your proposal with us: we don't want you to invest your time on changes we are already working on ourselves, or have different plans for. You can suggest changes as a [discussion](https://github.com/hashintel/hash/discussions) if it's a feature proposal, or an [issue](https://github.com/hashintel/hash/issues) if it's a bug you intend to fix. If you're unsure, you can always chat to us on [Discord](https://hash.ai/discord) first. If it's a typo or docs change, don't worry about this step.
+- Before undertaking any significant work, please share your proposal with us: we don't want you to invest your time on changes we are already working on ourselves, or have different plans for. You can suggest changes as a [discussion] if it's a feature proposal, or an [issue] if it's a bug you intend to fix. If you're unsure, you can always chat to us on [Discord] first. If it's a typo or docs change, don't worry about this step.
 - When submitting a pull request, please fill out any sections of the provided template you feel able to. If you are unsure or don't feel a section is relevant, please say so.
   - Always include a link to the issue or discussion proposing the change.
   - Write tests to accompany your PR, or ask for help/guidance if this is a blocker.
   - Make sure that your PR doesn’t break existing tests.
   - The repository follows a set of linting rules. Many of them can be applied automatically by running `yarn install` and `yarn fix`.
-  - Sign our _Contributor License Agreement_ at the CLA Assistant's prompting. (To learn more, read [why we have a CLA](https://hash.ai/legal/cla))
+  - Sign our _Contributor License Agreement_ at the CLA Assistant's prompting. (To learn more, read [why we have a CLA])
 - Once you have receive a pull request review, please bear the following in mind:
   - reviewers may make suggestions for _optional_ changes which are not required to get your code merged. It should be obvious which suggestions are optional, and which are required changes. If it is not obvious, ask for clarification.
   - please do not resolve comment threads unless you opened them - leave it to the person who raised a comment to decide if any further discussion is required (GitHub will also automatically resolve any code suggestions you click 'commit' on). Comment threads may also be left open so that they can be linked to later.
 
 ## How can I find interesting PRs to work on?
 
-Existing issues can provide a good source of inspiration for potential contributions. The issue tags `E-help-wanted` and `E-good-first-issue` flag some of the lower-hanging fruit that are available for people (including first-time contributors) to work on, without necessarily requiring prior discussion. You should also feel free to join our [HASH Discord](https://hash.ai/discord) and reach out directly to us for more inspiration. If you're willing to contribute, we'd love to have you!
+Existing issues can provide a good source of inspiration for potential contributions. The issue tags `E-help-wanted` and `E-good-first-issue` flag some of the lower-hanging fruit that are available for people (including first-time contributors) to work on, without necessarily requiring prior discussion. You should also feel free to join our [Discord] and reach out directly to us for more inspiration. If you're willing to contribute, we'd love to have you!
 
 ## Why might contributions be rejected?
 
@@ -42,11 +54,11 @@ There are a number of reasons why otherwise sound contributions might not find t
 - **PRs that introduce new functionality without proper tests will not be accepted.** You should write meaningful tests for your code.
 - **PRs that fail to pass tests will not be merged.** If your PR doesn’t pass our Continuous Integration tests, it won’t be merged.
 - **PRs that duplicate functionality which already exist in HASH, but outside of the project you're introducing them in.** For example, recreating functionality provided in one package directly within another.
-- **PRs that duplicate workstreams already under development at HASH** may be rejected, or alternatively integrated into working branches other than those intended by the contributor. For more on these, see our [public roadmap](https://hash.ai/roadmap).
+- **PRs that duplicate workstreams already under development at HASH** may be rejected, or alternatively integrated into working branches other than those intended by the contributor. For more on these, see our [public roadmap].
 - **PRs that add functionality that is only useful to a subset of users**, which may increase maintenance overheads on the product. We know it can be frustrating when these sorts of PRs are rejected, and it can sometimes seem arbitrary. We’ll do our best to communicate our rationale clearly in such instances and are happy to talk it out. It's impossible to forecast all of the possible use-cases of a product or feature, and we try to keep an open posture towards such contributions.
 - **PRs that introduce architectural changes to the project** (without prior discussion and agreement) will be rejected.
 - **PRs that don’t match the syntax, style and formatting of the project will be rejected.** See: _maintainability_.
 
 ## Can I work for HASH full-time?
 
-We're recruiting for a number of full-time roles. If you've already contributed to [this repository](https://github.com/hashintel/hash) or any of our other [@hashintel](https://github.com/hashintel)/[@blockprotocol](https://github.com/blockprotocol) repos, mention it in your application. View our open roles at [hash.ai/careers](https://hash.ai/careers) and drop your name in the mix _even if_ you can't see a good fit right now.
+We're continuously headhunting for full-time roles. However, as outlined on our [careers site], **you can't apply to work at HASH.**. Instead, we use the technology we've developed at HASH to scour the web for people we think would be a good fit to join us, and we reach out _to them_, rather than accept inbound applications. Nevertheless, a great (and guaranteed) way to get on our radar is to contribute to any of our open-source repositories, in particular [this one](https://github.com/hashintel/hash). If and when a good fit opens up, we may invite you to interview. If your contact email address or other information aren't accessible via your profile, we invite you to [tell us about yourself] nevertheless.

apps/hashdotdev/src/_pages/docs/10_contributing/01_architecture.mdx

@@ -11,18 +11,24 @@ HASH is built around a flexible type system which allows for information to be e
 
 ### System Concepts
 
-Most entities and types you work with in HASH will be user-created, or generated by [apps](https://hash.ai/guide/apps) or [integrations](https://hash.ai/guide/integrations). But there are also a number of core concepts which you'll likely want to familiarize yourself with as a developer building on HASH.
+Most entities and types you work with in HASH will be user-created, or generated by [workers](https://hash.ai/guide/workers), [apps](https://hash.ai/guide/apps) or [integrations](https://hash.ai/guide/integrations). But there are also a number of core concepts which you'll likely want to familiarize yourself with as a developer building on HASH.
 
 - **Instance:** a single running node of HASH, generally available via the world wide web (e.g. at a web address like `hash.ai`), deployed within a private network (e.g. available via a VPN), or running locally for development purposes.
 - **Instance Admin:** relevant in the context of self-hosting HASH, instance admins are users with the ability to perform instance-wide moderation and updates, or to change certain settings.
 - **Web:** a web is a namespace within an instance that contains **entities** and **types**, which belongs to either a user or an organization.
 - **User:** a single account on an instance, corresponding to a real person, which can be logged into via the HASH application interface.
 - **Organization:** a collectively addressable group of users on an instance.
+- **Worker:** an individual AI agent capable of conducting actions or co-ordinating other agents in service of a goal.
+- **Goal:** a user-defined objective provided in natural language.
+- **Flow:** a pre-defined set of steps that can be executed by workers.
+- **File:** a binary object stored as a single entity. Files MAY have a more specific system-recognized sub-type (e.g. `Image File`), extending the range of ways in which they can be used in HASH.
+
+A number of other system entity types exist:
+
 - **Block:** a discrete piece of UI in a page for editing or displaying data in a specific way (e.g. a Paragraph, Map, or Table block)
 - **Page:** a user-created page within a web containing any number of blocks. All pages MUST be either a:
-  1. **Document:** a linear page, whose blocks appear in one or more columns
-  1. **Canvas:** a freeform page, whose blocks can be dragged-and-dropped anywhere
-- **File:** a binary object stored as a single entity. Files MAY have a more specific system-recognized sub-type (e.g. `Image File`), extending the range of ways in which they can be used in HASH.
+  - **Document:** a linear page, whose blocks appear in one or more columns
+  - **Canvas:** a freeform page, whose blocks can be dragged-and-dropped anywhere
 
 ### System Components
 
@@ -39,8 +45,8 @@ We also make use of third-party open-source applications as part of:
 
 - **Authentication system:** based on Ory Kratos and Hydra, handles user accounts, sessions and access tokens. Managed by the Node API.
 - **Authorization system:** based on SpiceDB, extends a Zanzibar-like way of providing permissionsed access to information. Managed by the Graph.
-- **Execution system:** based on Temporal, powers [flows](https://hash.ai/guide/flows)
-- **Datastore(s):** currently Postgres, with planned support for additional specialized backends for selectively storing/offloading specific kinds of data (e.g. timeseries, financial/accounting) and queries (e.g. full-text/vector search). Managed by the Graph.
-- **Blobstore(s):** currently supportive of S3-compatible APIs (with Cloudflare R2 utilized by default), with planned for support for file-type specific handlers (e.g. Cloudflare Images for images, Cloudflare Stream for video). Managed by the Node API.
+- **Execution system:** based on Temporal, powers AI [workers](https://hash.ai/guide/workers) who run [flows](https://hash.ai/guide/flows) and complete [goals](https://hash.ai/guide/workers/goals)
+- **Data storage:** currently Postgres, with planned support for additional specialized backends for selectively storing/offloading specific kinds of data (e.g. timeseries, financial/accounting) and queries (e.g. full-text/vector search). Managed by the Graph.
+- **Object storage:** currently supportive of S3-compatible APIs (with Cloudflare R2 utilized by default in production environments, alongside minio locally), with planned for support for file-type specific handlers (e.g. Cloudflare Images for images, Cloudflare Stream for video). Managed by the Node API.
 
-More information about each of these, as well as the corresponding code, can be found in the `hash-` prefixed subdirectories within [`apps`](https://github.com/hashintel/hash/tree/main/apps) (in our [`@hashintel/hash` public monorepo](https://github.com/hashintel)):
+More information about each of these, as well as the corresponding code, can be found in the `hash-` prefixed subdirectories within [`apps`](https://github.com/hashintel/hash/tree/main/apps) (in our [`@hashintel/hash` public monorepo](https://github.com/hashintel)).

apps/hashdotdev/src/_pages/docs/10_contributing/WIP_02_reference.mdx

@@ -81,6 +81,8 @@ The `Global Public Graph` is a planned initiative which will allow for unifyied
 - `TransactionTime`: The time point when an entity or a type was inserted into the datastore (precisely the time when the transaction started to create that record)
 - `DecisionTime`: The time when a user decided something should go into the data store. This defaults to the `TransactionTime`.
 
+_In the future, we plan to additionally support `ValidTime`, referring to the effective datetime(s) of a specific value._
+
 To uniquely identify an **entity edition**, you must specify both:
 
 1. The `EntityId`