Improve discoverability, SEO, and cross-linking across docs

SUMMARY.md

@@ -68,6 +68,7 @@
 
 * [Events](core/events/README.md)
   * [Topics](core/events/topics.md)
+  * [Event topics list](platform/events/topics.md)
   * [Parent and child events](core/events/parent-and-child-events.md)
 * [Tasks](core/tasks/README.md)
   * [Subscriptions](core/tasks/subscriptions.md)

core/actions/email.md

@@ -163,3 +163,9 @@ For more on this, see [File generators](file-generators/).
 
 {% endtab %}
 {% endtabs %}
+
+## Related
+
+* [Email](../../platform/email/) — email platform features, including custom domains, DMARC, and receiving inbound email
+* [Email templates](../../platform/email/templates.md) — reusable email layouts and styling
+* [File generators](file-generators/) — generate PDFs, CSVs, and other attachments for your emails

core/actions/file-generators/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Generate files from Mechanic tasks — PDF, CSV, ZIP, plaintext, and base64 formats for attachments and downloads.
+---
+
 # File generators
 
 **File generators** are invoked by [**actions**](../) to create new files, using options provided by the action, and handing the resulting file back to the action for further use. In this way, [**tasks**](../../tasks/) can make choices about what files to generate, and what to do with the results.

core/actions/http.md

@@ -165,3 +165,9 @@ mechanic/actions/perform
     response_body: action.run.result.body %}
 {% endif %}
 ```
+
+## Related
+
+* [Working with external APIs](../../techniques/working-with-external-apis/) — patterns for authenticating and integrating with third-party services
+* [Responding to action results](../../techniques/responding-to-action-results.md) — inspect HTTP responses and react to them in a follow-up task run
+* [Preventing action loops](../../techniques/preventing-action-loops.md) — guard against re-triggers when combining HTTP actions with event subscriptions

core/actions/integrations/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Connect Mechanic tasks to third-party services — Airtable, Google Sheets, Slack, Shopify Flow, and more.
+---
+
 # Integrations
 
 These actions allow your Mechanic tasks to speak to other app and systems :)  Use Mechanic to integrate your Shopify store with other apps like Airtable, Google, Slack, and more.

core/actions/shopify.md

@@ -141,3 +141,10 @@ This example shows how the query and variables may be built up separately, and p
 
 {% endtab %}
 {% endtabs %}
+
+## Related
+
+* [Reading Shopify data](../shopify/read/) — query products, orders, customers, and more using GraphQL in Liquid
+* [Writing Shopify data](../shopify/write.md) — overview of writing data to Shopify
+* [Responding to action results](../../techniques/responding-to-action-results.md) — inspect Shopify mutation results in a follow-up task run
+* [Preventing action loops](../../techniques/preventing-action-loops.md) — guard against re-triggers when modifying resources you subscribe to

core/events/README.md

@@ -21,6 +21,12 @@ Each event carries **data** that tasks can use. For a Shopify webhook event, thi
 
 For a complete reference of available event topics, see [Topics](topics.md).
 
+## What happens next
+
+When an event arrives, Mechanic creates a [**run**](../runs/) to process it. Each run evaluates every [task](../tasks/) that subscribes to that event's topic. If a task generates [actions](../actions/) (like a Shopify API call or an email), those actions are queued and performed after the task run completes.
+
+This is the core execution flow: **Event** → **Task Run** → **Action Run(s)**. To learn more, see [Runs](../runs/).
+
 {% hint style="info" %}
 Incoming events may be selectively skipped using [event filters](../../platform/events/filters.md). For handling high-frequency events, see [Debouncing events](../../techniques/debouncing-events.md).
 {% endhint %}

core/shopify/admin-action-links.md

@@ -9,7 +9,7 @@ description: >-
 For supported resources, you'll find **"Send to Mechanic"** links within the Shopify admin. These links point to a Mechanic app URL that translates selected Shopify resources into Mechanic events for on-demand processing. Depending on the user's resource and task selections, their submission may result in one or more new events. Event data consists of the latest stable REST Admin API representation of the selected resource(s).
 
 {% hint style="warning" %}
-**Important**: Starting **Feb 1, 2025**, the `product` and `variant` resource types will no longer include full REST Admin API data in these events. Instead, only resource IDs (`id` and `admin_graphql_api_id`) will be included, due to Shopify REST API deprecations. If you need additional product or variant details (e.g. title, vendor, etc.), you must fetch them via Shopify's GraphQL API.
+**Important**: As of **Feb 1, 2025**, the `product` and `variant` resource types no longer include full REST Admin API data in these events. Only resource IDs (`id` and `admin_graphql_api_id`) are included, due to Shopify REST API deprecations. If you need additional product or variant details (e.g. title, vendor, etc.), fetch them via Shopify's GraphQL API.
 {% endhint %}
 
 Tasks can qualify for this style of on-demand Shopify resource processing by subscribing to event topics like **mechanic/user/{resource}** (singular) for individual processing, and **mechanic/user/{resources}** (plural) for batch processing. See [Supported resources](admin-action-links.md#supported-resources) below for a complete table of resources and event topics.
@@ -21,7 +21,7 @@ Shopify admin action links are a form of [**run link**](../../platform/integrati
 <table><thead><tr><th width="175.33333333333331">Resource object</th><th width="173">URL parameter</th><th width="255">Individual mode event topic</th><th width="325">Batch mode event topic</th></tr></thead><tbody><tr><td><a href="https://shopify.dev/api/admin-rest/latest/resources/customer#resource-object">Customer</a></td><td><code>customer</code></td><td>mechanic/user/customer</td><td>mechanic/user/customers</td></tr><tr><td><a href="https://shopify.dev/api/admin-rest/latest/resources/order#resource-object">Order</a></td><td><code>order</code></td><td>mechanic/user/order</td><td>mechanic/user/orders</td></tr><tr><td><a href="https://shopify.dev/api/admin-rest/latest/resources/draftorder#resource-object">Draft order</a></td><td><code>draft_order</code></td><td>mechanic/user/draft_order</td><td>mechanic/user/draft_orders</td></tr><tr><td><a href="https://shopify.dev/api/admin-rest/latest/resources/product#resource-object">Product</a></td><td><code>product</code></td><td>mechanic/user/product</td><td>mechanic/user/products</td></tr><tr><td><a href="https://shopify.dev/api/admin-rest/latest/resources/product-variant#resource-object">Product variant</a></td><td><code>variant</code></td><td>mechanic/user/variant</td><td>mechanic/user/variants</td></tr><tr><td><a href="https://shopify.dev/api/admin-rest/latest/resources/collection#resource-object">Collection</a></td><td><code>collection</code></td><td>mechanic/user/collection</td><td></td></tr></tbody></table>
 
 {% hint style="warning" %}
-**Note**: After **Feb 1, 2025**, `product` and `variant` events will only include resource IDs:
+**Note**: As of **Feb 1, 2025**, `product` and `variant` events only include resource IDs:
 
 ```
 {

core/shopify/events/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Respond to Shopify webhooks in Mechanic — subscribe to store activity and handle changes to orders, products, customers, and more.
+---
+
 # Responding to events
 
 Shopify uses webhooks to notify apps like Mechanic about new activity. Mechanic supports every type of Shopify webhook in its set of [**Shopify event topics**](../../../platform/events/topics.md#shopify). By setting up [**subscriptions**](../../tasks/subscriptions.md) to these topics, a task may respond to any supported type of Shopify activity.

core/shopify/read/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Read Shopify store data in Mechanic tasks — GraphQL queries, bulk operations, and the shopify Liquid filter.
+---
+
 # Reading data
 
 Mechanic supports several methods of reading data. The following articles discuss usage, and when each technique might \(or might not\) be appropriate:

core/shopify/read/liquid-objects.md

@@ -3,9 +3,9 @@
 Mechanic-flavored Liquid comes with a complement of [Liquid objects](../../../platform/liquid/objects/), each of which is tied to a resource in the [Shopify Admin REST API](https://shopify.dev/docs/admin-api/rest). Many objects support access to related objects via lookups (e.g. `{{ shop.customers[customer_id].orders.first }}`); in this way, the REST API can be traversed by resource.
 
 {% hint style="danger" %}
-**Shopify is deprecating some of the Shopify Admin REST API. The first round of deprecations involve the product and variant endpoints. Read the deprecation notice** [**here**](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model#whats-changing)**.** 
+**Shopify has deprecated the REST Admin API that these Liquid objects depend on.** The product and variant endpoints were removed on Feb 1, 2025, and Shopify is phasing out the remaining REST endpoints over time. Read more [here](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model#whats-changing).
 
-Our recommendation is to use [GraphQL](../../actions/shopify.md#graphql) going forward. The [product](../../../platform/liquid/objects/shopify/product.md) and [variant](../../../platform/liquid/objects/shopify/variant.md) objects will cease to work on on Feb 1, 2025 due to the changes being made by Shopify. It appears that Shopify will gradually phase out the REST API over time.
+Use [GraphQL](../../actions/shopify.md#graphql) going forward. The [product](../../../platform/liquid/objects/shopify/product.md) and [variant](../../../platform/liquid/objects/shopify/variant.md) objects no longer work. The remaining REST objects will follow as Shopify continues the migration.
 
 All of our [library tasks](https://tasks.mechanic.dev/) will be ported to use GraphQL only, which will provide a model for how you can update your custom tasks. You'll be able to update your non-customized library tasks with a click of a button :relaxed:
 {% endhint %}

core/tasks/advanced-settings/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Per-task configuration beyond code and options — documentation, JavaScript, and action sequencing.
+---
+
 # Advanced settings
 
 Advanced settings are per-task configuration options beyond the task's code and user-facing options. They control how the task is documented, how its code is executed, and how its actions are performed.

core/tasks/code/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Write task code in Mechanic's Liquid environment — render actions, logs, and errors in response to events.
+---
+
 # Code
 
 A task's code is a [**Liquid**](../../../platform/liquid/) template. In the same way that a Shopify storefront might use a Liquid template to receive requests and render HTML, a task uses its Liquid code to receive events, and render a series of JSON objects. These JSON objects define [**actions**](action-objects.md), [**logs**](log-objects.md), and [**errors**](error-objects.md).
@@ -17,3 +22,11 @@ A task must purposefully consider its [**preview**](../previews/), so as to accu
 {% hint style="info" %}
 To find many examples of task code, browse [https://github.com/lightward/mechanic-tasks](https://github.com/lightward/mechanic-tasks).
 {% endhint %}
+
+## See also
+
+* [Liquid basics](../../../platform/liquid/basics/) — syntax, data types, variables, filters, and control flow
+* [Mechanic filters](../../../platform/liquid/filters/) — Mechanic-specific filters for data manipulation
+* [Mechanic tags](../../../platform/liquid/tags/) — `{% raw %}{% action %}{% endraw %}`, `{% raw %}{% log %}{% endraw %}`, `{% raw %}{% error %}{% endraw %}`, and more
+* [Mechanic objects](../../../platform/liquid/objects/) — event, task, options, cache, and action objects available in your code
+* [Writing a high-quality task](../../../techniques/writing-a-high-quality-task.md) — patterns and practices for reliable Mechanic tasks

core/tasks/import-and-export.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Share and back up Mechanic tasks as JSON — import individually or in bulk, and contribute to the task library.
+---
+
 # Import and export
 
 Mechanic tasks may be imported and exported as JSON, using the "Import" or "Export" button below the task editor. The JSON schema used for representing tasks is identical to that used by the **task library**, making it suitable for [contributing to the task library](../../resources/task-library/contributing.md).

core/tasks/options/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Add user-facing configuration to your Mechanic tasks — input fields, validation flags, and custom option types.
+---
+
 # Options
 
 [**Tasks**](../) can accept user configuration via **options**. Options are created automatically: when you reference `options.something` in your task's [**code**](../code/), Mechanic adds an input field for it in the task configuration UI.

core/tasks/permissions.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  How Mechanic determines Shopify API access scopes from your task code — automatic detection and explicit declarations.
+---
+
 # Permissions
 
 Mechanic determines Shopify API access scopes (like `read_orders` or `write_products`) from your task code. It can infer scopes from several places, including subscriptions, Shopify data access in task code, and actions rendered during preview. When your shop needs additional access, Mechanic will surface that in the app.

core/tasks/previews/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Test Mechanic tasks safely before they run on real data — preview actions, request Shopify permissions, and define sample events.
+---
+
 # Previews
 
 A task uses its **preview** to demonstrate what actions the task intends to generate. Among other purposes (see below), this is also how tasks request the Shopify permissions they require.

core/tasks/user-form.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Create custom input forms for manually-triggered Mechanic tasks — collect user input and pass it to your task code.
+---
+
 # User Form
 
 When a task subscribes to the **mechanic/user/form** event topic a "Run task" button is added to the task.

platform/cache/README.md

@@ -18,4 +18,12 @@ The cache is intended for temporary data storage. As such, each stored value is
 
 The cache is not intended for large value storage. As such, each stored value is limited to a maximum of 256kb.
 
-For storing larger values, consider spreading the value across multiple cache keys, or using the [FTP](../../core/actions/ftp.md) action to upload data to another storage service (possibly using a service like [Couchdrop](https://couchdrop.io/) as a intermediary). To read larger values in task code, use the [HTTP](../../core/actions/http.md) action to perform a GET request, then [respond to the action's results](../../techniques/responding-to-action-results.md).\
+For storing larger values, consider spreading the value across multiple cache keys, or using the [FTP](../../core/actions/ftp.md) action to upload data to another storage service (possibly using a service like [Couchdrop](https://couchdrop.io/) as a intermediary). To read larger values in task code, use the [HTTP](../../core/actions/http.md) action to perform a GET request, then [respond to the action's results](../../techniques/responding-to-action-results.md).
+
+## Common patterns
+
+The cache is a versatile tool — here are some of the ways it's commonly used:
+
+* [Debouncing events](../../techniques/debouncing-events.md) — use the cache to skip duplicate events that arrive in rapid succession
+* [Batch processing of events](../../techniques/batch-processing-of-events.md) — accumulate data in the cache across multiple events, then process it all at once on a schedule
+* [Responding to action results](../../techniques/responding-to-action-results.md) — store state across the multiple task runs in a multi-step workflow

platform/email/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Send automated emails from Mechanic — templates, custom domains, DMARC, and receiving inbound email.
+---
+
 # Email
 
 Mechanic email is powered by [Postmark](https://postmarkapp.com/).

platform/events/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Mechanic event sources, topics, and filters — Shopify webhooks, scheduled events, custom triggers, and more.
+---
+
 # Events
 
 In Mechanic, an [event](../../core/events/) represents something that happened — a new order, a scheduled timer firing, an incoming email, or a custom trigger. Events are the starting point for all automation: every task run begins with an event.

platform/graphql/basics/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  GraphQL fundamentals for Mechanic — queries, mutations, pagination, and the Shopify Admin API.
+---
+
 # Basics
 
 GraphQL is a query language used to request data from APIs and it is also a runtime for fulfilling these requests. When working with GraphQL, you'll use [queries](queries.md) and [mutations](mutations.md) to query a GraphQL serve and responses will come back in JSON format. GraphQL is the future of Shopify APIs, and Shopify has said: "You should expect that there absolutely will be more features that will be only on GraphQL in the future."

platform/liquid/basics/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Learn the fundamentals of Liquid in Mechanic — syntax, data types, variables, filters, operators, and control flow.
+---
+
 # Basics
 
 Mechanic uses [**Liquid**](../), a template language created by Shopify. If you have worked with the code behind Shopify themes, you've worked with Liquid.

platform/liquid/basics/control-flow/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Control flow in Liquid — conditionals and iteration for directing task logic in Mechanic.
+---
+
 # Control flow
 
 In Liquid, **control flow** determines what code is evaluated. By using control flow tags, developers can use logic to activate different parts of code, and skip over other parts.

platform/liquid/filters/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Complete reference of Liquid filters available in Mechanic — shopify, parse_json, csv, hmac_sha256, and more.
+---
+
 # Mechanic filters
 
 This page defines all of the [**Liquid filters**](../basics/filters.md) that are available in Mechanic Liquid. Mechanic supports many of our own filters, as well as an array of filters drawn from Shopify Liquid.

platform/liquid/keyword-literals/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Mechanic's keyword literals for Liquid — array, hash, and newline for working with data structures and formatting.
+---
+
 # Keyword literals
 
 Mechanic adds several keyword literals to Liquid — special values that can be used directly in expressions without needing to be assigned or constructed. These make it easier to work with common data structures and formatting.

platform/liquid/objects/README.md

@@ -1,3 +1,8 @@
+---
+description: >-
+  Mechanic's Liquid objects — event, task, options, cache, action, and Shopify resource objects available in your task code.
+---
+
 # Mechanic objects
 
 Mechanic makes a variety of [**Liquid environment variables**](../../../core/tasks/code/environment-variables.md) available, containing specific Liquid objects. (The `shop` variable, for example, is always available and always contains the [Shop object](shopify/shop.md).)