Implement planned topic: 0001-standalone-activities (#224)

* Add Python standalone activities reference

* Add TypeScript standalone activities reference

* Add .NET standalone activities reference

* Add Java standalone activities reference

* Finalize draft for 0001-standalone-activities

* remove incomplete sections

* Add core page which abstracts out all shared stuff

* Standardize connection logic

* Unify worker setup section across SDK standalone-activity refs

Rename the worker section to "Worker setup & activity registration" in
all four SDK files and lead with a single sentence noting the Activity
is defined and registered exactly as normal. Drop the .NET "Define the
Activity" section so no file repeats how to define an activity, matching
the Python structure.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* re-organize to a LOGICAL structure, not just a flat list of H2 headings.

* finish cleaning up parts other than calling activities

* Get client connection in order

* cleanup of operations content

* Add links

---------

Co-authored-by: skill-sync[bot] <skill-sync[bot]@users.noreply.github.com>
Co-authored-by: Donald Pinckney <donald.pinckney@temporal.io>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 4 people

SKILL.md

@@ -71,6 +71,8 @@ Check if `temporal` CLI is installed. If not, follow the instructions at `refere
   - Language-specific info at `references/{your_language}/gotchas.md`
 - **`references/core/versioning.md`** - Versioning strategies and concepts - how to safely change workflow code while workflows are running
   - Language-specific info at `references/{your_language}/versioning.md`
+- **`references/core/standalone-activities.md`** - Standalone Activities: run an Activity directly from a Client without a Workflow (Public Preview)
+  - Language-specific info at `references/{your_language}/standalone-activities.md`
 - **`references/core/troubleshooting.md`** - Decision trees, recovery procedures
 - **`references/core/error-reference.md`** - Common error types, workflow status reference
 - **`references/core/interactive-workflows.md`** - Testing signals, updates, queries

references/core/standalone-activities.md

@@ -0,0 +1,160 @@
+> [!NOTE]
+> Standalone Activities are in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview.
+
+# Standalone Activities (Concepts)
+
+This document provides core conceptual explanations of Standalone Activities in Temporal. For language-specific implementation details, see `references/{your_language}/standalone-activities.md` for the language you are working in (Python, TypeScript, Java, .NET).
+
+## What is a Standalone Activity?
+
+A **Standalone Activity** is a top-level Activity Execution started directly by a Client, without using a Workflow. It is Temporal's job queue — the simplest way to run a single durable, retryable task.
+
+The rule of thumb:
+
+- **Need to orchestrate multiple Activities?** Use a Workflow.
+- **Just need to execute a single Activity?** Use a Standalone Activity.
+
+The same Activity Function code runs in both modes with no changes — the only difference is how it is invoked. An Activity defined for a Workflow can also be executed standalone, and the Worker that hosts it does not need to know how it will be invoked.
+
+Compared to wrapping a single Activity in a Workflow, a Standalone Activity:
+
+- Reduces billable actions in Temporal Cloud.
+- Lowers latency for short-lived executions (fewer Worker round-trips).
+- Lives in a separate ID space from Workflows.
+
+### Use cases
+
+Standalone Activities fit durable single-job processing where you don't need multi-step orchestration:
+
+- Sending an email
+- Processing a webhook
+- Syncing data
+- Any single-function task that benefits from built-in retries and timeouts
+
+### Key features
+
+- Execute Activities as a top-level primitive, without Workflow overhead.
+- Native async job lifecycle: **schedule → dispatch → process → result**.
+- Arbitrary-length jobs, with heartbeats for progress tracking.
+- **At-least-once execution by default**, with native retry policy and timeouts.
+- **At-most-once execution** when the retry policy's maximum attempts is 1.
+- Addressable by Activity ID / Run ID for result retrieval, cancellation, and termination.
+- Deduplication via configurable conflict policies.
+- Priority and fairness support.
+- Full visibility — list and count executions.
+
+## Using Standalone Activities
+
+### Defining activities
+
+Defining standalone activities is IDENTICAL to defining activities callable from a workflow - there is no distinction AT ALL between the two at activity definition or worker configuration site. Follow language-specific guidance for how to normally define activities and configure workers to run them.
+
+### Calling and Interacting with Standalone Activities
+
+The CLI and every SDK exposes the same conceptual operations against a Standalone Activity (method names differ per language — see the language reference):
+
+- **Execute** — durably enqueue the Activity, wait for a Worker to run it, and return the result.
+- **Start** — durably enqueue the Activity and return a handle immediately, without waiting.
+- **Get handle** — rebind a handle to a previously started Activity by ID (and optionally Run ID).
+- **Get result** — wait on a handle for completion. `execute` is equivalent to `start` followed by awaiting the handle's result.
+- **Cancel / Terminate** — via the handle or CLI.
+
+**Choosing an Activity ID.** Every Standalone Activity call requires an **Activity ID**, which uniquely identifies that one call. It is the key you use later to get the result, describe, cancel, or terminate the Activity, and it is what conflict/reuse policies dedupe against. Use a **business-logic identifier** that uniquely identifies the call — for example `send-welcome-email:user-42`, `sync-invoice:INV-2026-001`, or `process-webhook:<event-id>`. This makes Activities addressable and naturally deduplicated by your domain. Only if you genuinely have no meaningful business-level identifier should you generate a **UUID** to use as the Activity ID.
+
+Visibility operations are available as well:
+- **List** — enumerate Standalone Activity Executions matching a query. Only Standalone Activities are returned; Activities running inside Workflows are not included.
+- **Count** — return the total number of executions matching a query (running, completed, failed, etc. — not the number of queued tasks).
+- **Describe** — via the handle or CLI.
+
+See below for a quick reference how to call these operations from the CLI rather than SDKs.
+
+> [!IMPORTANT]
+> When using an SDK, these operations are owned by the Temporal Client, and belong **in your non-workflow application code**. It is INVALID to call an activity as a standalone activity from within a workflow: you instead should use standard within-workflow activity calls.
+
+**Currently Supported SDKs: Python, TypeScript, Java, .NET**
+
+## Quick CLI Standalone Activity Man Page
+
+Ultimately, any standalone activity invocation code should live in your application code and use the appropriate SDK, but the Temporal CLI is a quick and easy way to test invoking standalone activities during development. All subcommands live under `temporal activity`.
+
+The key operations are:
+
+**Execute (start and wait for the result).** Blocks until the Activity completes and prints the result to stdout. Requires `--activity-id`, `--type`, `--task-queue`, and at least one of `--start-to-close-timeout` / `--schedule-to-close-timeout`:
+
+```bash
+temporal activity execute \
+  --activity-id my-activity-id \
+  --type ComposeGreeting \
+  --task-queue my-task-queue \
+  --start-to-close-timeout 10s \
+  --input '{"some-key": "some-value"}'
+```
+
+`--input` takes a JSON value; pass it multiple times for multiple positional arguments. `--input-file` is also a convenient option for larger inputs. The same required flags apply to `start` below.
+
+Reminder: `--activity-id` must be unique across all activity calls, as discussed above.
+
+**Start (do not wait).** Enqueues the Activity and prints the Activity ID and Run ID without blocking:
+
+```bash
+temporal activity start \
+  --activity-id my-activity-id \
+  --type ComposeGreeting \
+  --task-queue my-task-queue \
+  --start-to-close-timeout 10s \
+  --input '{"some-key": "some-value"}'
+```
+
+Outputs this JSON shape:
+
+```json
+{
+  "activityId": "my-activity-id",
+  "runId": "019e84d3-949a-7a0e-ae78-63b8a0b172bd",
+  "namespace": "default"
+}
+```
+
+**Result (wait for a started Activity).** Waits for completion and prints the result. `--run-id` is optional and defaults to the latest run of that Activity ID:
+
+```bash
+temporal activity result --activity-id my-activity-id
+```
+
+**Describe (current state of one Activity).** Shows status, run state, task queue, timeouts, attempt count, etc.:
+
+```bash
+temporal activity describe --activity-id my-activity-id
+```
+
+**List / Count (visibility across many Activities).** Only Standalone Activity Executions are returned (Activities running inside Workflows are not):
+
+```bash
+temporal activity list
+temporal activity count
+```
+
+**Cancel / Terminate (stop an Activity).** `cancel` requests cooperative cancellation (surfaced to the Activity on its next heartbeat response); `terminate` forcefully ends it (Activity code cannot see or respond to it). Both accept `--reason`:
+
+```bash
+temporal activity cancel    --activity-id my-activity-id --reason "no longer needed"
+temporal activity terminate --activity-id my-activity-id --reason "no longer needed"
+```
+
+## Observability
+
+All existing Activity metrics apply to Standalone Activities (scheduled, started, completed, failed, timed out, canceled).
+
+## Public Preview limitations
+
+- Pause, reset, and update options are not supported (scheduled for GA).
+- The `TerminateExisting` conflict policy and `TerminateIfRunning` reuse policy are not yet supported.
+
+## Temporal CLI support
+
+- Requires **Temporal CLI v1.7.0+** and **Temporal Server v1.31.0+**. See `references/core/install_cli.md` if you need to update the CLI.
+- The Temporal Dev Server (`temporal server start-dev`) has Standalone Activities enabled by default.
+
+## Temporal Cloud support
+
+Standalone Activities are available in Temporal Cloud as a Public Preview feature. Because the SDK client config loaders read environment variables and TOML profiles, the same code runs against a local server or Temporal Cloud with no code changes.

references/dotnet/dotnet.md

@@ -199,4 +199,5 @@ See `references/dotnet/testing.md` for info on writing tests.
 - **`references/dotnet/advanced-features.md`** — Schedules, worker tuning, dependency injection
 - **`references/dotnet/data-handling.md`** — Data converters, payload encryption, etc.
 - **`references/dotnet/versioning.md`** — Patching API, workflow type versioning, Worker Versioning
+- **`references/dotnet/standalone-activities.md`** — Standalone Activities: run an Activity directly from a Client without a Workflow (Public Preview). Concept overview at `references/core/standalone-activities.md`.
 - **`references/dotnet/determinism-protection.md`** — Runtime task detection, .NET Task determinism rules

references/dotnet/standalone-activities.md

@@ -0,0 +1,156 @@
+> [!NOTE]
+> This feature is in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview.
+
+## Overview
+
+Standalone Activities are Activities run independently of any Workflow, started directly from a Temporal Client — useful when you need a single durable, retryable task (job-queue style) and not multi-step orchestration. The same Activity method can be executed both as a Standalone Activity and as a Workflow Activity with no code changes.
+
+Standalone Activities are conceptually the same across all SDKs. Read the [cross-SDK concept file](references/core/standalone-activities.md) if you have not already, and then see below for the .NET SDK specific APIs for calling Standalone Activities.
+
+## Prerequisites
+
+- Temporal .NET SDK v1.12.0 or higher.
+- Temporal CLI v1.7.0 or higher — see [Temporal CLI install instructions](references/core/install_cli.md) if needed. Dev server includes Standalone Activities support.
+- For production, Temporal Server v1.31.0 or higher (or Temporal Cloud).
+
+## Hosting Activities on a Worker
+
+The Activity is defined just as activities normally are in Temporal. Worker registration is also the same.
+
+```csharp
+using Microsoft.Extensions.Logging;
+using Temporalio.Client;
+using Temporalio.Common.EnvConfig;
+using Temporalio.Worker;
+using TemporalioSamples.StandaloneActivity;
+
+var connectOptions = ClientEnvConfig.LoadClientConnectOptions();
+connectOptions.TargetHost ??= "localhost:7233";
+connectOptions.LoggerFactory = LoggerFactory.Create(builder =>
+    builder.
+        AddSimpleConsole(options => options.TimestampFormat = "[HH:mm:ss] ").
+        SetMinimumLevel(LogLevel.Information));
+var client = await TemporalClient.ConnectAsync(connectOptions);
+
+const string taskQueue = "standalone-activity-sample";
+
+using var tokenSource = new CancellationTokenSource();
+Console.CancelKeyPress += (_, eventArgs) =>
+{
+    tokenSource.Cancel();
+    eventArgs.Cancel = true;
+};
+
+using var worker = new TemporalWorker(
+    client,
+    new TemporalWorkerOptions(taskQueue).
+        AddActivity(MyActivities.ComposeGreetingAsync)); // register whatever your activity(ies) is/are
+
+await worker.ExecuteAsync(tokenSource.Token);
+```
+
+## Calling and managing Standalone Activities
+
+Start and manage Standalone Activities from your application code using the Temporal Client.
+
+### Do not call from inside a Workflow
+
+Don't call `client.ExecuteActivityAsync` / `client.StartActivityAsync` or any other Standalone Activity APIs from inside a Workflow Definition — use Workflow-side activity invocation (`Workflow.ExecuteActivityAsync`) instead.
+
+### Connect a Client
+
+The Standalone Activity operations are methods on a connected `TemporalClient`. The examples below assume this `client`.
+
+```csharp
+using Temporalio.Client;
+using Temporalio.Common.EnvConfig;
+
+var connectOptions = ClientEnvConfig.LoadClientConnectOptions();
+connectOptions.TargetHost ??= "localhost:7233";
+var client = await TemporalClient.ConnectAsync(connectOptions);
+```
+
+### Execute (wait for result)
+
+Use `client.ExecuteActivityAsync(...)` to durably enqueue the Activity, wait for it to run on a Worker, and return the result. The activity options require `Id`, `TaskQueue`, and at least one of `ScheduleToCloseTimeout` or `StartToCloseTimeout`.
+
+#### With type checking
+
+Use when activity definitions are available in this language. Pass a lambda invoking the activity method:
+
+```csharp
+// In practice, use a meaningful business identifier, like customer or transaction identifier
+var activityId = Guid.NewGuid().ToString();
+
+var result = await client.ExecuteActivityAsync(
+    () => MyActivities.ComposeGreetingAsync(new ComposeGreetingInput("Hello", "World")),
+    new(activityId, "standalone-activity-sample")
+    {
+        ScheduleToCloseTimeout = TimeSpan.FromSeconds(10),
+    });
+```
+
+#### Without type checking
+
+Use when activity definitions are unavailable in this language (i.e. you can't import them). Pass the activity type name as a string and an argument array:
+
+```csharp
+var result = await client.ExecuteActivityAsync<string>(
+    "ComposeGreeting",
+    new object?[] { new ComposeGreetingInput("Hello", "World") },
+    new(activityId, "standalone-activity-sample")
+    {
+        ScheduleToCloseTimeout = TimeSpan.FromSeconds(10),
+    });
+```
+
+### Start (do not wait for result)
+
+Use `client.StartActivityAsync(...)` to durably enqueue the Activity and get back a handle without waiting for completion. This takes the **exact same arguments as `ExecuteActivityAsync`**.
+
+```csharp
+var handle = await client.StartActivityAsync(...);
+```
+
+### Get a handle to an existing Activity execution
+
+Use `client.GetActivityHandle(...)` to attach a handle to a previously started Standalone Activity. Passing `null` as the run ID (the default) targets the latest run of that Activity ID.
+
+```csharp
+// Without a known result type
+var handle = client.GetActivityHandle("my-activity-id", runId: "the-run-id");
+
+// With a known result type
+var typedHandle = client.GetActivityHandle<string>("my-activity-id", runId: "the-run-id");
+```
+
+### Wait for the result of a handle
+
+```csharp
+var result = await handle.GetResultAsync();
+```
+
+Calling `ExecuteActivityAsync` is equivalent to `StartActivityAsync` followed by `await handle.GetResultAsync()`.
+
+### List Standalone Activities
+
+```csharp
+await foreach (var info in client.ListActivitiesAsync(
+    "TaskQueue = 'standalone-activity-sample'")) // returns an IAsyncEnumerable<ActivityExecution>
+{
+    Console.WriteLine(
+        $"ActivityID: {info.ActivityId}, Type: {info.ActivityType}, Status: {info.Status}");
+}
+```
+
+Only Standalone Activity Executions are returned; Activities running inside Workflows are not included.
+
+### Count Standalone Activities
+
+Use `client.CountActivitiesAsync(query)` to count matching executions; this takes the **exact same arguments as `ListActivitiesAsync`**.
+
+```csharp
+var resp = await client.CountActivitiesAsync(
+    "TaskQueue = 'standalone-activity-sample'");
+Console.WriteLine($"Total activities: {resp.Count}");
+```

references/java/java.md

@@ -263,6 +263,7 @@ See `references/java/testing.md` for info on writing tests.
 - **`references/java/advanced-features.md`** - Schedules, worker tuning, and more
 - **`references/java/data-handling.md`** - Data converters, Jackson, payload encryption
 - **`references/java/versioning.md`** - Patching API, workflow type versioning, Worker Versioning
+- **`references/java/standalone-activities.md`** - Standalone Activities: run an Activity directly from a Client without a Workflow (Public Preview). Concept overview at `references/core/standalone-activities.md`.
 
 ### Java Integrations