docs(developer): document the Workflow Step Type module comprehensively

[geeksman]

Summary

The workflow-step-type module requires the crowdin_agent authentication type, but this constraint — and the crowdin_agent type itself — was not documented. Installing an app with any other authentication type fails manifest validation with "Only crowdin_agent authentication type is allowed for workflow-step-type module type", and there was no public documentation explaining why or how to configure agent authentication.

This PR significantly expands the Workflow Step Type module documentation and documents the crowdin_agent authentication type across related articles. It also incorporates the technical review feedback (accuracy corrections, section restructuring, and terminology alignment).

developer/modules/other/workflow-step-type.mdx (main rewrite)

• How It Works – the asynchronous, webhook-driven integration model
• Requirements – what an app with this module must include, and which of the requirements are validated at installation vs. surface later (a missing companion Webhook module produces no install error: strings are silently never delivered, and a validation error appears only on later workflow saves)
• Authentication – why the module requires crowdin_agent, the agent (bot) user concept, the agent descriptor block, and the full token flow (grant_type: crowdin_agent, agentId from the Installed event)
• Boundaries and Ports – port semantics, connection rules, initial is input-only, max 2 outputs
• String statuses on a custom step and Delivery Guarantees and Reconciliation (per-minute batching, limited retries, failed strings recovery via Resend, periodic reconciliation via the GET endpoint)
• Expanded API methods (agent-token requirement, query params, replace-only PATCH semantics, examples aligned with the sample manifest's declared ports), JWT-signed settings lifecycle callbacks (project and template payloads), Recommended Implementation Flow, and a Troubleshooting table quoting the real validation messages
• Fixed the Properties table (copy-pasted "custom AI's logo" description, required/optional flags for logo/description)
• Section order aligned with sibling module articles; simple tables use Markdown

enterprise/.../app-based-workflow-step.mdx

• New Bot User section (matching the Enterprise UI terminology): what the bot is, how it gets manager access (assigned to all projects at install, or invited per project), and why not to remove it
• Troubleshooting additions: manager-permission warnings and failed strings recovery (Resend)

developer/crowdin-apps/app-descriptor.mdx, security.mdx, and installation.mdx

• crowdin_agent documented as a third authentication type with links to the module page
• The Installed event documented as used for both crowdin_app and crowdin_agent (payload additionally carries agentId)

Notes

• Verified with astro check (0 errors) and a full astro build — all pages build and every internal link is valid

🤖 Generated with Claude Code

[vercel]

Someone is attempting to deploy a commit to the Crowdin Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 6, 2026 3:14pm

[geeksman]

Code review

Found 2 issues:

1. The installed event description in the Events table still says the event is only for crowdin_app ("This event is required if you use crowdin_app"), which now contradicts this PR's own changes: the Authentication section documents crowdin_agent, the payload table documents agentId, and installation.mdx was updated to say the Installed event is used for both types. This row needs the same update.

docs/src/content/docs/developer/crowdin-apps/app-descriptor.mdx

Lines 259 to 261 in 3199a5d

	<p><strong>Description:</strong> The event that is sent to an app after a user installed the app in Crowdin.</p>
	<p>This event is required if you use <code>crowdin_app</code>. Read more about [Authentication](#authentication).</p>
	</td>

2. The Update String Status example contradicts the new rule stated just above it. The rule says value must be one of the output ports declared in the module's boundaries.outputs, but the article's own sample manifest declares only translated and untranslated outputs, while the request body example uses "value": "approved" and the response example shows "output": "true". A developer copying the article's manifest and the example request would get the 400 Bad Request described in Troubleshooting. The example values should be aligned with the declared ports (e.g. translated/untranslated).

docs/src/content/docs/developer/modules/other/workflow-step-type.mdx

Lines 650 to 658 in 3199a5d

	"path": "/1106423/output",
	"value": "translated"
	},
	{
	"op": "replace",
	"path": "/1106430/output",
	"value": "approved"
	}
	]

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}