docs: enrich Actor development pages from help-center articles

sources/platform/actors/development/builds_and_runs/builds.md

@@ -5,6 +5,8 @@ sidebar_position: 7
 slug: /actors/development/builds-and-runs/builds
 ---
 
+A build packages a specific version of your Actor's source code and settings into a runnable Docker image. This page explains how builds and build numbers work, how to version your Actor and tag its builds, and how to manage the build cache.
+
 ## Understand Actor builds
 
 Before an Actor can be run, it needs to be built. The build process creates a snapshot of a specific version of the Actor's settings, including its [source code](../actor_definition/source_code.md) and [environment variables](../programming_interface/environment_variables.md). This snapshot is then used to create a Docker image containing everything the Actor needs for its run, such as `npm` packages, web browsers, etc.
@@ -35,6 +37,16 @@ For example, an Actor might have:
 - Beta version _1.2_ that contains new features but is still backward compatible
 - Development version _2.0_ that contains breaking changes.
 
+### Best practices for public Actors
+
+If you publish your Actor for others to use, treat your version tags as a stable contract with your users:
+
+- Avoid pinning users to `latest`. Give each version a descriptive tag (for example, `0.0` or `1.0`) so users can depend on a stable version instead of being moved onto every change automatically.
+- Ship non-breaking changes under the same tag. For bug fixes and performance improvements that keep the same input and output, keep the version tag and let the build number increment automatically. Record the change in your Actor's changelog.
+- Fork a new version for breaking changes. When you change the input schema or output format, create a new version with a new tag (for example, from `0.0` to `0.1`). Existing users stay on the previous version until they choose to upgrade.
+- Set the default version deliberately. New users get the default version first, so point it at your newest stable version.
+- Migrate off `latest` gradually. If your Actor currently builds only under `latest`, fork the current version to a new tag, set it as the default, and use tagged versions from then on.
+
 ## Tags
 
 Tags simplify the process of specifying which build to use when running an Actor. Instead of using a version number, you can use a tag such as _latest_ or _beta_. Tags are unique, meaning only one build can be associated with a specific tag.

sources/platform/actors/development/deployment/continuous_integration.md

@@ -1,23 +1,22 @@
 ---
 title: Continuous integration for Actors
 sidebar_label: Continuous integration
-description: Set up automated builds, deploys, and tests for your Actors using GitHub Actions, webhooks, or the official GitHub integration.
+description: Set up continuous integration for your Actors to automate builds, deploys, and tests with GitHub Actions, webhooks, GitHub integration, or Bitbucket Pipelines.
 slug: /actors/development/deployment/continuous-integration
 sidebar_position: 2
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
----
-
 Automating your Actor development process can save time and reduce errors, especially for projects with multiple Actors or frequent updates. Instead of manually pushing code, building Actors, and running tests, you can automate these steps to run whenever you push code to your repository.
 
 Set up continuous integration for your Actors using one of these methods:
 
 - [GitHub Actions](#github-actions) - the most flexible approach, with support for tests, multi-branch builds, and custom workflows.
 - [API webhook](#api-webhook) - works with Bitbucket, GitLab, and other Git hosting providers that support webhooks.
 - [GitHub integration](#github-integration) - the quickest setup with no workflow files needed, but less flexible than GitHub Actions.
+- [Bitbucket Pipelines](#bitbucket-pipelines) - run tests and push your Actor from Bitbucket on every commit.
 
 ## Set up automated builds with GitHub Actions {#github-actions}
 
@@ -156,16 +155,46 @@ For example, in GitHub, go to **Settings** > **Webhooks** > **Add webhook** and
 
 ![GitHub integration](./images/ci-github-integration.png)
 
-:::tip Bitbucket Pipelines
-
-For a more complete Bitbucket setup with automated tests, see the [Bitbucket CI guide](https://help.apify.com/en/articles/6988586-setting-up-continuous-integration-for-apify-actors-on-bitbucket).
-
-:::
-
 ## Use the Apify GitHub integration {#github-integration}
 
 Apify Console includes a built-in [GitHub integration](/integrations/github) that links an Actor directly to a GitHub repository. When you connect a repository, Apify automatically rebuilds the Actor on every push - no workflow files or webhook configuration needed.
 
 This is the quickest way to get automated builds running, but it's less flexible than the GitHub Actions approach. It doesn't support running tests before building, managing multiple version tags from different branches, or customizing the build pipeline.
 
 To set it up, see the [GitHub integration](/integrations/github) documentation.
+
+## Set up Bitbucket Pipelines {#bitbucket-pipelines}
+
+If you host your Actor's source code on Bitbucket, you can use [Bitbucket Pipelines](https://bitbucket.org/product/features/pipelines) to run tests and push your Actor to the Apify platform on every commit. Unlike the [webhook approach](#api-webhook), this pushes your source code to the platform, so you don't need to link the Actor to the repository in Apify Console.
+
+1. In Bitbucket, go to **Repository settings** > **Repository variables** and add a variable named `APIFY_TOKEN` with your Apify API token as its value. Mark it as **Secured** so it isn't exposed in build logs.
+1. Add a `bitbucket-pipelines.yml` file to the root of your repository. The following example runs your tests, then pushes and builds the Actor, tagging builds from your production branch as `latest` and builds from your development branch as `beta`:
+
+   ```yaml
+   image: node:22
+
+   pipelines:
+     branches:
+       master:
+         - step:
+             caches:
+               - node
+             script:
+               - npm install
+               - npm test
+               - npm install -g apify-cli
+               - apify login --token $APIFY_TOKEN
+               - apify push --build-tag latest
+       develop:
+         - step:
+             caches:
+               - node
+             script:
+               - npm install
+               - npm test
+               - npm install -g apify-cli
+               - apify login --token $APIFY_TOKEN
+               - apify push --build-tag beta
+   ```
+
+Because `npm test` runs before `apify push`, a failing test stops the pipeline and keeps a broken build from reaching the platform. Adjust the branch names to match your repository's branching model.

sources/platform/actors/publishing/monetize/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Monetize your Actor
-description: Monetize your Actors on Apify Store and earn regular passive income.
+description: Monetize your Actors on Apify Store by choosing a pricing model, earning passive income from paying users, and tracking revenue with built-in analytics.
 slug: /actors/publishing/monetize
 sidebar_position: 2.5
 ---
@@ -106,6 +106,24 @@ When monetizing your Actor, you might want to limit features or usage for users
 - Graceful exits: If a free user hits a limit, don't crash the Actor or return a system error. Instead, exit gracefully with a clear [status message](/actors/development/programming-interface/status-messages#communicating-limitations) explaining the limit (e.g., "Free tier limit reached").
 - Avoid confusion: Never make a policy restriction look like a bug or platform error.
 
+## Compensate users for failed runs
+
+If a run fails or returns bad results because of a problem with your Actor, you can compensate the affected user with Apify platform credits. The amount is deducted from your payout.
+
+1. The user reports the problem on your Actor's **Issues** tab.
+1. Review the issue and decide whether it's valid. Ask the user for the run details, such as the run ID or a shared run link, so you can verify what happened before you approve anything.
+1. If the compensation is warranted, open the Apify support chat, select **Request user credit compensation**, and fill in the requested details: the user ID, the Actor ID, the amount, and the reason (or a link to the issue). Apify then credits the user's account.
+
+<img src={require('./images/request-user-credit-compensation.webp').default} alt="The Request user credit compensation option in the Apify support chat" width="320" />
+
+The **Request user credit compensation** option appears in the Apify support chat only for Actor developers. If you're contacting support as a user, you won't see it.
+
+Keep a few things in mind when handling compensations:
+
+- Compensation is paid in platform credits and deducted from your payout, not refunded as money. Describe it to users as credits - for example, "We'll compensate you for the run with credits" - rather than as a refund.
+- Don't post specific compensation amounts publicly on the **Issues** tab.
+- If you and the user can't agree, or the user insists on a monetary refund, raise it in the Apify support chat through the same option for an impartial review.
+
 ## Actor analytics
 
 Monitor your Actors' performance through the [Actor Analytics](https://console.apify.com/actors/insights/analytics) dashboard under **Development > Insights > Analytics**.

sources/platform/actors/running/usage_and_resources.md

@@ -5,6 +5,8 @@ sidebar_position: 2
 slug: /actors/running/usage-and-resources
 ---
 
+Every Actor run uses platform resources - memory, CPU, and disk space - and how much it uses directly affects what the run costs. This page explains how Apify allocates these resources to an Actor, how usage is measured in compute units, and how to estimate and reduce what your runs consume.
+
 ## Resources
 
 [Actors](../index.mdx) run in [Docker containers](https://www.docker.com/resources/what-container/), which have a [limited amount of resources](https://phoenixnap.com/kb/docker-memory-and-cpu-limit) (memory, CPU, disk size, etc). When starting, the Actor needs to be allocated a certain share of those resources, such as CPU capacity that is necessary for the Actor to run.
@@ -48,7 +50,7 @@ Sometimes, you see the Actor's CPU use go over 100%. This is not unusual. To hel
 
 The Actor has hard disk space limited by twice the amount of memory. For example, an Actor with `1024MB` of memory will have `2048MB` of disk available.
 
-## Requirements
+## Choose the right memory
 
 Actors built with [Crawlee](https://crawlee.dev/) use autoscaling. This means that they will always run as efficiently as they can based on the allocated memory. If you double the allocated memory, the run should be twice as fast and consume the same amount of [compute units](#what-is-a-compute-unit) (1 * 1 = 0.5 * 2).
 
@@ -64,11 +66,11 @@ If the Actor doesn't have this information, or you want to use your own solution
 
 :::tip Estimating usage
 
-Check out the article on [estimating consumption](https://help.apify.com/en/articles/3470975-how-to-estimate-compute-unit-usage-for-your-project) for more details.
+See [reference consumption rates](#reference-consumption-rates) for approximate figures, or [measure your own usage with a test run](#measure-consumption-with-a-test-run).
 
 :::
 
-### Memory requirements
+### Minimum memory
 
 Each use case has its own memory requirements. The larger and more complex your project, the more memory/CPU power it will require. Some examples which have minimum requirements are:
 
@@ -147,4 +149,19 @@ The factors that influence resource consumption, in order of importance, are:
 
 - _Page type_: Heavy pages, such as Amazon or Facebook will take more time to load regardless whether you use a browser or Cheerio. Large pages can take up to _3 times_ more resources to load and parse than average pages.
 
-You can check out our [article on estimating consumption](https://help.apify.com/en/articles/3470975-how-to-estimate-compute-unit-usage-for-your-project) for more details on what determines consumption.
+#### Reference consumption rates
+
+These approximate figures can help you size a project before running it at scale. Treat them as order-of-magnitude ballparks rather than guarantees - your actual usage depends on the target site, page size, and your code.
+
+- Browser-based scraping (Puppeteer or Playwright): roughly 300 pages per CU.
+- Plain HTTP scraping (Cheerio): roughly 3,000 pages per CU.
+- Downloading and uploading images: more than 10,000 images per CU.
+- A short browser workflow (load a page, log in, and click a few buttons): about 0.01 CU per run.
+
+#### Measure consumption with a test run
+
+To get a figure specific to your project, run a controlled test instead of relying on averages:
+
+1. Prepare a request list of about 1,000 URLs. To exercise a single page repeatedly, duplicate one URL and give each request a randomized `uniqueKey` so the requests aren't deduplicated.
+1. Allocate memory appropriate to your tooling - for example, `128MB` to `512MB` for Cheerio, or `1024MB` or more for Puppeteer or Playwright.
+1. Run the Actor, then open the run's details and check its exact CU usage. Divide the CUs consumed by the number of pages processed to get your per-page cost, then scale that up to your target volume.