td-ai-tools 1.3.4 → 1.3.6

package/skills/shopify-lint/theme-check-theory/.theme-check.example.yml

@@ -12,6 +12,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 # Upstream check, pinned here so the branch lint always fails on it: Shopify
 # serves `{% stylesheet %}` and `{% javascript %}` bodies verbatim, so Liquid
 # written inside one ships to the browser as literal text.

package/skills/shopify-lint/theme-check-theory/README.md

@@ -13,6 +13,7 @@ integrated into Shopify CLI. It is not compatible with the archived Ruby
 | --- | --- | --- |
 | `DisallowedScriptOrStyleTag` | warning | An inline executable `<script>` or any `<style>` tag in a Liquid file. |
 | `HardcodedText` | warning | Rendered hard-coded storefront copy that should use a dynamic content source. |
+| `RequiredLiquidDoc` | warning | A `td-` snippet or theme block without a complete Liquid doc contract. |
 | `UnusedSectionSettings` | warning | A setting declared in `{% schema %}` that is never referenced in the file. |
 | `UnguardedNullableSetting` | warning | A potentially blank setting output with `{{ }}` and no presence guard (`{% if %}`/`{% unless %}`) or `\| default`. |
 | `UnguardedMetafield` | warning | A metafield output with no presence guard or `\| default`. |
@@ -33,12 +34,18 @@ Rendered storefront copy should come from a section setting, translation key,
 metafield, or metaobject. The check reports text nodes, direct quoted output
 with `{{ }}` or `{% echo %}`, quoted `default` filter fallbacks, hard-coded
 `alt`, `title`, `placeholder`, and ARIA text attributes, and labels in the
-`value` attribute of button-like inputs. Text inside inline SVG elements and
-string literals passed as named `render` or `include` arguments are also
+`value` attribute of button-like inputs. Text inside inline SVG elements is also
 checked. It ignores technical attributes such as classes and IDs, Liquid logic
 strings, comments, punctuation-only fragments, and text made entirely of HTML
 character references.
 
+String literals passed as named `{% render %}` and `{% include %}` arguments are
+ignored. A snippet argument is as often a class name, icon key, size token, or
+heading level as it is storefront copy, and nothing at the call site separates
+the two, so checking them produced mostly false positives. Copy that a snippet
+renders is still reported inside the snippet itself, where it appears as a text
+node or a quoted output.
+
 Text beginning with `--` is ignored as a CSS custom property name: Liquid
 routinely assembles a custom property declaration before handing it to a
 `style` attribute or a `{% style %}` block, neither of which this check reads.
@@ -52,6 +59,36 @@ accepted. Short alphabetic tokens and copyright years remain reportable because
 the check cannot reliably distinguish user-facing copy from currency codes,
 units, or other intentional literals.
 
+### RequiredLiquidDoc
+
+Files whose name contains `td-` under `snippets/` or `blocks/` must contain a
+`{% doc %}` tag with a prose description and a non-empty `@example`. Every
+`@param` that is present must use LiquidDoc's `{type} name - description`
+shape; optional names such as `[heading]` are supported. LiquidDoc types are
+descriptive rather than a closed type system, so Shopify Liquid object names,
+primitive names, and project-specific type expressions are all accepted.
+
+```liquid
+{% doc %}
+  Renders a product card.
+
+  @param {product} product - The product to display.
+  @param {string} [heading] - An optional card heading.
+
+  @example
+  {% render 'td-product-card', product: product, heading: 'Featured' %}
+{% enddoc %}
+```
+
+The check does not infer missing parameters from variable lookups inside the
+file. Liquid exposes many global objects, and a snippet parameter is introduced
+at its call site, so a single-file lookup cannot reliably distinguish the two.
+To require complete parameter coverage, add a separate project-level analysis
+that indexes named arguments at static `{% render %}` call sites and compares
+their union with each target file's documented parameters. Dynamic snippet
+names and values passed with `with`/`for` require an explicit project policy or
+an allowlist.
+
 ### UnusedSectionSettings
 
 This single-file check collects every `id` under `settings` and
@@ -185,6 +222,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 # Upstream check, pinned here so the branch lint always fails on it: Shopify
 # serves `{% stylesheet %}` and `{% javascript %}` bodies verbatim, so Liquid
 # written inside one ships to the browser as literal text.

package/skills/shopify-lint/theme-check-theory/configs/recommended.yml

@@ -6,6 +6,10 @@ HardcodedText:
   enabled: true
   severity: warning
 
+RequiredLiquidDoc:
+  enabled: true
+  severity: warning
+
 UnusedSectionSettings:
   enabled: false
   severity: warning

package/skills/shopify-lint/theme-check-theory/src/checks/hardcoded-text.test.ts

@@ -98,22 +98,18 @@ describe('HardcodedText', () => {
     ]);
   });
 
-  it('reports string literals passed as render and include arguments', async () => {
+  it('ignores string literals passed as render and include arguments', async () => {
+    // A snippet argument is as often a class name, icon key, size token, or
+    // heading level as it is storefront copy, and the call site carries nothing
+    // that separates the two. The snippet body is still checked on its own.
     const source = `
       {% render 'button', label: 'Add to cart' %}
       {% include 'icon', accessible_name: "Search icon" %}
-      {% render 'button', label: section.settings.button_label %}
+      {% render 'button', variant: 'primary', size: 'large' %}
       {% render 'icon' %}
     `;
 
-    const offenses = await runLiquidCheck(HardcodedText, source);
-
-    expect(offenses).toHaveLength(2);
-    expect(
-      offenses.map(({ start, end }) =>
-        source.slice(start.index, end.index),
-      ),
-    ).toEqual(["'Add to cart'", '"Search icon"']);
+    expect(await runLiquidCheck(HardcodedText, source)).toEqual([]);
   });
 
   it('reports hard-coded default filter fallbacks', async () => {

package/skills/shopify-lint/theme-check-theory/src/checks/hardcoded-text.ts

@@ -308,17 +308,6 @@ export const HardcodedText: LiquidCheckDefinition = {
 
         reportInlineSvgText(node);
       },
-
-      async RenderMarkup(node) {
-        for (const argument of node.args) {
-          if (
-            argument.type === NodeTypes.NamedArgument &&
-            argument.value.type === NodeTypes.String
-          ) {
-            reportString(argument.value);
-          }
-        }
-      },
     };
   },
 };

package/skills/shopify-lint/theme-check-theory/src/checks/required-liquid-doc.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { liquidDocProblems, requiresLiquidDoc } from './required-liquid-doc';
+
+describe('RequiredLiquidDoc', () => {
+  it('targets td- Liquid snippets and blocks only', () => {
+    expect(requiresLiquidDoc('file:///theme/snippets/td-card.liquid')).toBe(true);
+    expect(requiresLiquidDoc('/theme/blocks/product-td-card.liquid')).toBe(true);
+    expect(requiresLiquidDoc('/theme/sections/td-card.liquid')).toBe(false);
+    expect(requiresLiquidDoc('/theme/snippets/card.liquid')).toBe(false);
+  });
+
+  it('accepts a description, typed parameters, and an example', () => {
+    const body = `
+      Renders a card for a product.
+      @param {product} product - The product displayed by the card.
+      @param {string} [heading] - An optional heading.
+      @example
+      {% render 'td-card', product: product, heading: 'Featured' %}
+    `;
+    expect(liquidDocProblems(body)).toEqual([]);
+  });
+
+  it('requires both a description and non-empty example', () => {
+    expect(liquidDocProblems('@example\n').map(({ message }) => message)).toEqual([
+      'Liquid doc must include a description before its annotations',
+      'Liquid doc must include an @example with example markup',
+    ]);
+  });
+
+  it('requires types and descriptions on documented parameters', () => {
+    const body = `
+      Renders a card.
+      @param product - The product.
+      @param {string} heading
+      @example
+      {% render 'td-card', product: product %}
+    `;
+    expect(liquidDocProblems(body).map(({ message }) => message)).toEqual([
+      'Liquid doc @param must include a type in braces',
+      'Liquid doc @param must include a description after " - "',
+      'Liquid doc @param must include a type in braces',
+      'Liquid doc @param must include a description after " - "',
+    ]);
+  });
+});

package/skills/shopify-lint/theme-check-theory/src/checks/required-liquid-doc.ts

@@ -0,0 +1,111 @@
+import type { LiquidRawTag } from '@shopify/liquid-html-parser';
+import {
+  LiquidCheckDefinition,
+  Severity,
+  SourceCodeType,
+} from '@shopify/theme-check-common';
+
+type DocumentationProblem = { message: string; offset: number; length: number };
+
+const PARAM_LINE = /^[ \t]*@param[ \t]+(.*)$/gm;
+const COMPLETE_PARAM = /^\{([^}\n]+)\}\s+(\[[^\]\n]+\]|[^\s-]+)\s+-\s+(.+)$/;
+
+/** Returns true for td-named snippets and theme blocks. */
+export function requiresLiquidDoc(uri: string): boolean {
+  const path = decodeURIComponent(uri).replace(/\\/g, '/').split(/[?#]/, 1)[0];
+  const match = path.match(/(?:^|\/)(snippets|blocks)\/([^/]+)\.liquid$/i);
+  return Boolean(match?.[2].toLowerCase().includes('td-'));
+}
+
+/** Validates the documented contract without mistaking Shopify globals for parameters. */
+export function liquidDocProblems(body: string): DocumentationProblem[] {
+  const problems: DocumentationProblem[] = [];
+  const firstAnnotation = body.search(/^[ \t]*@\w+/m);
+  const description = body.slice(0, firstAnnotation < 0 ? body.length : firstAnnotation).trim();
+
+  if (!description) {
+    problems.push({
+      message: 'Liquid doc must include a description before its annotations',
+      offset: 0,
+      length: Math.max(body.length, 1),
+    });
+  }
+
+  const example = body.match(
+    /^[ \t]*@example[^\n]*\n([\s\S]*?)(?=^[ \t]*@\w+|(?![\s\S]))/m,
+  );
+  if (!example || !example[1].trim()) {
+    problems.push({
+      message: 'Liquid doc must include an @example with example markup',
+      offset: 0,
+      length: Math.max(body.length, 1),
+    });
+  }
+
+  for (const match of body.matchAll(PARAM_LINE)) {
+    const complete = match[1].trim().match(COMPLETE_PARAM);
+    const offset = match.index ?? 0;
+    if (!complete?.[1].trim()) {
+      problems.push({
+        message: 'Liquid doc @param must include a type in braces',
+        offset,
+        length: match[0].length,
+      });
+    }
+    if (!complete?.[3].trim()) {
+      problems.push({
+        message: 'Liquid doc @param must include a description after " - "',
+        offset,
+        length: match[0].length,
+      });
+    }
+  }
+
+  return problems;
+}
+
+export const RequiredLiquidDoc: LiquidCheckDefinition = {
+  meta: {
+    code: 'RequiredLiquidDoc',
+    name: 'Require documentation for td- snippets and theme blocks',
+    docs: {
+      description:
+        'Requires td- snippets and blocks to have a Liquid doc description and example, and validates documented parameters.',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+  },
+  create(context) {
+    const uri = (context as unknown as { file?: { uri?: string } }).file?.uri ?? '';
+    if (!requiresLiquidDoc(uri)) return {};
+
+    const docs: LiquidRawTag[] = [];
+    return {
+      async LiquidRawTag(node) {
+        if (node.name === 'doc') docs.push(node);
+      },
+      async onCodePathEnd() {
+        if (docs.length === 0) {
+          context.report({
+            message: 'td- snippets and blocks must include a {% doc %} tag',
+            startIndex: 0,
+            endIndex: 1,
+          });
+          return;
+        }
+
+        const doc = docs[0];
+        for (const problem of liquidDocProblems(doc.body.value)) {
+          const startIndex = doc.body.position.start + problem.offset;
+          context.report({
+            message: problem.message,
+            startIndex,
+            endIndex: startIndex + problem.length,
+          });
+        }
+      },
+    };
+  },
+};

package/skills/shopify-lint/theme-check-theory/src/index.test.ts

@@ -8,6 +8,7 @@ describe('theme-check-theory module', () => {
     expect(checks.map(({ meta }) => meta.code)).toEqual([
       'DisallowedScriptOrStyleTag',
       'HardcodedText',
+      'RequiredLiquidDoc',
       'UnusedSectionSettings',
       'UnguardedNullableSetting',
       'UnguardedMetafield',
@@ -24,6 +25,7 @@ describe('theme-check-theory module', () => {
     ).toEqual({
       DisallowedScriptOrStyleTag: true,
       HardcodedText: true,
+      RequiredLiquidDoc: true,
       UnusedSectionSettings: false,
       UnguardedNullableSetting: true,
       UnguardedMetafield: true,

package/skills/shopify-lint/theme-check-theory/src/index.ts

@@ -1,5 +1,6 @@
 import { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
 import { HardcodedText } from './checks/hardcoded-text';
+import { RequiredLiquidDoc } from './checks/required-liquid-doc';
 import { UnusedSectionSettings } from './checks/unused-section-settings';
 import { UnguardedMetafield } from './checks/unguarded-metafield';
 import { UnguardedMetaobject } from './checks/unguarded-metaobject';
@@ -7,6 +8,7 @@ import { UnguardedNullableSetting } from './checks/unguarded-nullable-setting';
 
 export { DisallowedScriptOrStyleTag } from './checks/disallowed-script-or-style-tag';
 export { HardcodedText } from './checks/hardcoded-text';
+export { RequiredLiquidDoc } from './checks/required-liquid-doc';
 export { UnusedSectionSettings } from './checks/unused-section-settings';
 export { UnguardedMetafield } from './checks/unguarded-metafield';
 export { UnguardedMetaobject } from './checks/unguarded-metaobject';
@@ -18,6 +20,7 @@ export {
 export const checks = [
   DisallowedScriptOrStyleTag,
   HardcodedText,
+  RequiredLiquidDoc,
   UnusedSectionSettings,
   UnguardedNullableSetting,
   UnguardedMetafield,

package/skills/forge-cli/references/api-databases-and-backups.md

@@ -1,48 +0,0 @@
-# Forge API — Databases, Database Users, Backups
-
-Endpoint paths are relative to `https://forge.laravel.com/api/v1`.
-
-Statamic context: many Statamic sites are flat-file and need none of this. Use these endpoints when the project uses Statamic Eloquent, search drivers like MySQL, runs Laravel auth tables, or simply needs MySQL/Postgres for app-level data.
-
-## Databases
-
-| Operation       | Method | Path                                                  | Body                              |
-| --------------- | ------ | ----------------------------------------------------- | --------------------------------- |
-| List            | GET    | `/servers/{serverId}/databases`                       | —                                 |
-| Create          | POST   | `/servers/{serverId}/databases`                       | required: `name`; optional: `user`, `password` (creates a user in one shot) |
-| Get             | GET    | `/servers/{serverId}/databases/{databaseId}`          | —                                 |
-| Delete          | DELETE | `/servers/{serverId}/databases/{databaseId}`          | Destructive — data is gone        |
-| Sync            | POST   | `/servers/{serverId}/databases/sync`                  | Reconcile Forge state with what's actually on the server (use if databases were created outside Forge) |
-
-## Database Users
-
-| Operation       | Method | Path                                                          | Body                                                              |
-| --------------- | ------ | ------------------------------------------------------------- | ----------------------------------------------------------------- |
-| List            | GET    | `/servers/{serverId}/database-users`                          | —                                                                 |
-| Create          | POST   | `/servers/{serverId}/database-users`                          | required: `name`, `password`, `databases[]` (array of DB IDs)     |
-| Get             | GET    | `/servers/{serverId}/database-users/{userId}`                 | —                                                                 |
-| Update          | PUT    | `/servers/{serverId}/database-users/{userId}`                 | optional: `databases[]` — replaces the access set                 |
-| Delete          | DELETE | `/servers/{serverId}/database-users/{userId}`                 | —                                                                 |
-
-To grant an existing user access to a new database, PUT the full list of database IDs you want it to have, not just the addition.
-
-## Backup Configurations
-
-Forge can run scheduled mysqldump/pg_dump to S3, DigitalOcean Spaces, or any S3-compatible store. For a Statamic site backed by a database, this is the standard way to get off-server backups.
-
-| Operation             | Method | Path                                                                                | Body / notes                                                                                                                  |
-| --------------------- | ------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| List configs          | GET    | `/servers/{serverId}/backup-configs`                                                | —                                                                                                                             |
-| Create config         | POST   | `/servers/{serverId}/backup-configs`                                                | required: `provider` (`s3`, `spaces`, `custom`), `credentials`, `frequency`, `databases[]`; optional: `directory`, `email`, `retention` (number to keep) |
-| Get config            | GET    | `/servers/{serverId}/backup-configs/{backupConfigurationId}`                        | —                                                                                                                             |
-| Update config         | PUT    | `/servers/{serverId}/backup-configs/{backupConfigurationId}`                        | Same fields as create                                                                                                         |
-| Run backup now        | POST   | `/servers/{serverId}/backup-configs/{backupConfigurationId}`                        | Triggers a one-off run, on top of the schedule                                                                                |
-| Delete config         | DELETE | `/servers/{serverId}/backup-configs/{backupConfigurationId}`                        | Stops future backups; does not remove existing archives from object storage                                                   |
-| Restore one backup    | POST   | `/servers/{serverId}/backup-configs/{backupConfigurationId}/backups/{backupId}`     | optional: `database` (specific DB ID to restore into)                                                                         |
-| Delete one backup     | DELETE | `/servers/{serverId}/backup-configs/{backupConfigurationId}/backups/{backupId}`     | Removes the archive from the remote store                                                                                     |
-
-Notes:
-
-- Statamic content lives on disk under `content/`, `assets/`, and (sometimes) `users/`. Database backups alone do not cover these — pair with a filesystem snapshot or Statamic's own backup add-on for full coverage.
-- The `credentials` shape varies per provider (e.g. S3 wants `key`, `secret`, `region`, `bucket`). Check the Forge UI for the exact field names if creating from scratch.
-- `frequency` accepts standard cron-style scheduling — confirm in the Forge UI before creating programmatically.

package/skills/forge-cli/references/api-overview.md

@@ -1,90 +0,0 @@
-# Forge HTTP API Overview
-
-Use this reference when the Forge CLI does not expose an operation you need. The CLI covers day-to-day deploys, env management, logs, restarts, and Tinker; the HTTP API covers everything else (site creation, PHP version changes, SSL issuance, workers, scheduler integration, backups, recipes, and more).
-
-The API pages in this directory are scoped to operations that apply to **Statamic sites** (a Laravel-based flat-file or DB-backed CMS). WordPress, Octane, Reverb, Pulse, Horizon, Inertia SSR, load balancers, and server provisioning are intentionally omitted.
-
-## Authentication and Transport
-
-- Base URL: `https://forge.laravel.com/api/v1`
-- Header: `Authorization: Bearer <FORGE_API_TOKEN>`
-- Always send `Accept: application/json` and, for write requests, `Content-Type: application/json`.
-- Reuse the same `FORGE_API_TOKEN` the CLI uses. If it is not in the env, ask the user; do not try to read tokens from disk.
-
-```bash
-curl -sS https://forge.laravel.com/api/v1/user \
-  -H "Authorization: Bearer $FORGE_API_TOKEN" \
-  -H "Accept: application/json"
-```
-
-## When to Use the API Instead of the CLI
-
-| Need                                          | CLI?                  | API?                                                        |
-| --------------------------------------------- | --------------------- | ----------------------------------------------------------- |
-| Deploy a site, view logs, push env            | Yes                   | Optional                                                    |
-| Create a new site / install a repo            | No                    | Yes — `POST /servers/{id}/sites` + `POST .../git`           |
-| Change a site's PHP version                   | No                    | Yes — `PUT .../sites/{id}/php`                              |
-| Issue or renew Let's Encrypt SSL              | No                    | Yes — `POST .../certificates/letsencrypt`                   |
-| Edit deployment script or Nginx config        | No                    | Yes — `PUT .../deployment/script` or `PUT .../nginx`        |
-| Create queue workers, daemons, scheduled jobs | No                    | Yes                                                         |
-| Enable Laravel scheduler or maintenance mode  | No                    | Yes                                                         |
-| Create/restore database backups               | No                    | Yes                                                         |
-| Run a saved Recipe across servers             | No                    | Yes                                                         |
-| Add a webhook for deploys                     | No                    | Yes                                                         |
-
-Statamic note: many sites do not run a queue or scheduler. Only create workers, daemons, or scheduled jobs when the project actually defines queue connections or `php please schedule:run` tasks; do not provision them by default.
-
-## Finding IDs the API Needs
-
-Almost every endpoint needs `serverId` and most need `siteId`. The CLI can supply both without separate API calls:
-
-```bash
-forge server:list           # → server IDs and names
-forge server:current        # → active server ID
-forge site:list             # → site IDs on the active server
-```
-
-If scripting, list via API:
-
-```bash
-curl -sS "$BASE/servers"                       # all servers on the account
-curl -sS "$BASE/servers/$SERVER/sites"         # all sites on a server
-```
-
-## Common Response Codes
-
-| Code | Meaning                                                |
-| ---- | ------------------------------------------------------ |
-| 200  | Success                                                |
-| 204  | Success with no body (e.g. delete, clear logs)         |
-| 400  | Request failed despite valid data                      |
-| 401  | Invalid or missing API token                           |
-| 404  | Resource not found (wrong server/site ID is the usual) |
-| 422  | Validation error — body lists which fields are wrong   |
-| 429  | Rate-limited — back off and retry                      |
-| 500  | Forge-side server error                                |
-
-422 responses include a JSON body of field-level errors. Read it before retrying.
-
-## Convention Used in These References
-
-Each endpoint table shows:
-
-- Method and path (relative to `https://forge.laravel.com/api/v1`)
-- Required body fields, then optional ones
-- Notes that are easy to miss (enum values, side effects, "this returns plain text not JSON", etc.)
-
-Example invocation pattern used throughout:
-
-```bash
-BASE="https://forge.laravel.com/api/v1"
-AUTH=(-H "Authorization: Bearer $FORGE_API_TOKEN" -H "Accept: application/json")
-JSON=(-H "Content-Type: application/json")
-
-curl -sS "${AUTH[@]}" "${JSON[@]}" \
-  -X POST "$BASE/servers/$SERVER/sites/$SITE/deployment/deploy"
-```
-
-## Deprecation Notice
-
-The official docs flag the v1 API as deprecated with a discontinuation date of June 30, 2026. Until a v2 is announced for general use, v1 is what the CLI itself targets and what these references describe. Re-check the [official API docs](https://forge.laravel.com/api-documentation) before doing migration work.

package/skills/forge-cli/references/api-php-services-recipes.md

@@ -1,88 +0,0 @@
-# Forge API — PHP, Services, Server Logs, Recipes, Composer Auth
-
-Endpoint paths are relative to `https://forge.laravel.com/api/v1`.
-
-## PHP Versions on a Server
-
-| Operation         | Method | Path                                       | Body / notes                                                                                                            |
-| ----------------- | ------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| List installed    | GET    | `/servers/{serverId}/php`                  | Each entry has `status`, `displayable_version`, `binary_name`, and flags for default and CLI version                    |
-| Install a version | POST   | `/servers/{serverId}/php`                  | `version`: `php84`, `php83`, `php82`, `php81`, `php80`, `php74`, `php73`, `php72`, `php71`, `php70`, `php56`            |
-| Patch update      | POST   | `/servers/{serverId}/php/update`           | `version`: same enum — patches the named major.minor to its latest point release                                        |
-| Enable OPCache    | POST   | `/servers/{serverId}/php/opcache`          | Use in production after the site is stable; do not enable on dev servers where you're actively editing PHP              |
-| Disable OPCache   | DELETE | `/servers/{serverId}/php/opcache`          | —                                                                                                                       |
-
-Statamic version floor — install the matching PHP version on the server before pointing a site at it:
-
-| Statamic | Required PHP |
-| -------- | ------------ |
-| 4.x      | 8.1+         |
-| 5.x      | 8.2+         |
-
-After installing a new PHP version, set it on the site with `PUT /servers/{id}/sites/{siteId}/php` (`version`).
-
-## Service Control (start / stop / restart)
-
-| Service             | Method | Path                                       | Body / notes                                       |
-| ------------------- | ------ | ------------------------------------------ | -------------------------------------------------- |
-| MySQL reboot        | POST   | `/servers/{serverId}/mysql/reboot`         | —                                                  |
-| MySQL stop          | POST   | `/servers/{serverId}/mysql/stop`           | —                                                  |
-| Postgres reboot     | POST   | `/servers/{serverId}/postgres/reboot`      | —                                                  |
-| Postgres stop       | POST   | `/servers/{serverId}/postgres/stop`        | —                                                  |
-| Nginx reboot        | POST   | `/servers/{serverId}/nginx/reboot`         | —                                                  |
-| Nginx stop          | POST   | `/servers/{serverId}/nginx/stop`           | —                                                  |
-| Nginx test config   | GET    | `/servers/{serverId}/nginx/test`           | Returns parse errors, if any. Run this before reloading after edits to site nginx blocks. |
-| PHP-FPM reboot      | POST   | `/servers/{serverId}/php/reboot`           | Body: `version` — same enum as PHP install         |
-| Generic start       | POST   | `/servers/{serverId}/services/start`       | Body: service name                                 |
-| Generic stop        | POST   | `/servers/{serverId}/services/stop`        | Body: service name                                 |
-| Generic restart     | POST   | `/servers/{serverId}/services/restart`     | Body: service name                                 |
-
-After editing site Nginx config via the API, hit `GET .../nginx/test`. If it passes, `POST .../nginx/reboot` (or rely on Forge to reload — the API also accepts a reload via the update endpoint).
-
-## Server Logs
-
-| Operation       | Method | Path                                  | Body / notes                                                                                                                |
-| --------------- | ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Read a log      | GET    | `/servers/{serverId}/logs`            | Query `?file=` with one of `nginx_access`, `nginx_error`, `database`, `php7x`, `php56`. Returns a tail of the log as text.  |
-
-For day-to-day tailing, `forge nginx:logs`, `forge php:logs`, and `forge database:logs` are simpler than the API.
-
-## Recipes
-
-Recipes are saved provisioning scripts you can run across one or many servers. Handy for installing extra extensions Statamic add-ons might require (Imagick variants, FFmpeg for video transcoding, GhostScript for PDF assets, etc.) without redoing manual SSH steps.
-
-| Operation       | Method | Path                                  | Body                                                                  |
-| --------------- | ------ | ------------------------------------- | --------------------------------------------------------------------- |
-| List            | GET    | `/recipes`                            | —                                                                     |
-| Create          | POST   | `/recipes`                            | required: `name`, `user`, `script`                                    |
-| Get             | GET    | `/recipes/{recipeId}`                 | —                                                                     |
-| Update          | PUT    | `/recipes/{recipeId}`                 | `name`, `user`, `script`                                              |
-| Delete          | DELETE | `/recipes/{recipeId}`                 | —                                                                     |
-| Run             | POST   | `/recipes/{recipeId}/run`             | `servers[]` (server IDs), `notify` (bool — email when finished)       |
-
-`user` is the OS user the script runs as (`root` for installing system packages, `forge` for user-scoped work).
-
-## Composer Package Authentication (per site)
-
-Statamic Pro and many commercial add-ons live behind `https://composer.statamic.com` with a license-keyed username/password. Forge stores these as Composer auth credentials so deploys can install them.
-
-| Operation       | Method | Path                                                            | Body                                                                                                                 |
-| --------------- | ------ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| Get             | GET    | `/servers/{serverId}/sites/{siteId}/packages`                   | —                                                                                                                    |
-| Update          | PUT    | `/servers/{serverId}/sites/{siteId}/packages`                   | `credentials[]` with `{repository_url, username, password}` per entry — PUT replaces the full list                  |
-
-Typical Statamic entry:
-
-```json
-{
-  "credentials": [
-    {
-      "repository_url": "composer.statamic.com",
-      "username": "<site-domain>",
-      "password": "<statamic-pro-license-key>"
-    }
-  ]
-}
-```
-
-After updating, trigger a deploy so `composer install` runs with the new auth.