docs: reorganize actions v3 docs (#8712)

# Which Problems Are Solved

The actions v2 docs have broken links. Also, actions docs are
distributed and the navigation feels messy.

# How the Problems Are Solved

- The two actions v2 docs pages are integrated into the more accurate
actions v3 API section. Redirects are added to the Vercel config.


![image](https://github.com/user-attachments/assets/0b3b2255-4b90-45b3-be1d-ee875dd86f03)

![image](https://github.com/user-attachments/assets/a35314d7-11fb-446e-ae47-9d3e65adeccd)

- The broken links are fixed.

# Additional Changes

A text is added to the actions v3 section describing the changes coming
with v3.


![image](https://github.com/user-attachments/assets/bba0c9a2-36af-4820-aa84-a823b8801d79)

# Additional Context

- Replaces #8688
- Broken links reported in
https://discord.com/channels/927474939156643850/1275551972283646055
- Broken links reported in
https://discord.com/channels/927474939156643850/1168451861515354133/1280394234679136267

---------

Co-authored-by: Fabi <fabienne@zitadel.com>

docs/docs/apis/actions/v3/testing-locally.md

@@ -1,5 +1,5 @@
 ---
-title: Actions v2 example execution locally
+title: Test Actions Locally
 ---
 
 In this guide, you will create a ZITADEL execution and target. After a user is created through the API, the target is called.
@@ -52,7 +52,7 @@ What happens here is only a target which prints out the received request, which
 
 As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:
 
-[Create a target](/apis/resources/action_service_v3/action-service-create-target)
+[Create a target](/apis/resources/action_service_v3/zitadel-actions-create-target)
 
 ```shell
 curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/targets' \
@@ -75,7 +75,7 @@ Save the returned ID to set in the execution.
 
 To call the target just created before, with the intention to print the request used for user creation by the user V2 API, we define an execution with a method condition.
 
-[Set an execution](/apis/resources/action_service_v3/action-service-set-execution)
+[Set an execution](/apis/resources/action_service_v3/zitadel-actions-set-execution)
 
 ```shell
 curl -L -X PUT 'https://$CUSTOM-DOMAIN/v3alpha/executions' \
@@ -116,7 +116,7 @@ curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2/users/human' \
 }'
 ```
 
-Should print out something like, also described under [Sent information Request](./introduction#sent-information-request):
+Should print out something like, also described under [Sent information Request](./usage#sent-information-request):
 ```shell
 {
   "fullMethod": "/zitadel.user.v2.UserService/AddHumanUser",

docs/docs/apis/actions/v3/usage.md

@@ -1,8 +1,19 @@
 ---
-title: Actions V2
+title: Using Actions
 ---
 
-This page describes the options you have when defining ZITADEL Actions V2.
+The Action API provides a flexible mechanism for customizing and extending the functionality of ZITADEL. By allowing you to define targets and executions, you can implement custom workflows triggered on an API requests and responses, events or specific functions.
+
+**How it works:**
+- Create Target
+- Set Execution with condition and target
+- Custom Code will be triggered and executed
+
+**Use Cases:**
+- User Management: Automate provisioning user data to external systems when users are crreated, updated or deleted.
+- Security: Implement IP blocking or rate limiting based on API usage patterns.
+- Extend Workflows: Automatically setup resources in your application, when a new organization in ZITADEL is created. 
+- Token extension: Add custom claims to the tokens.
 
 ## Endpoints
 
@@ -51,7 +62,7 @@ There are different types of Targets:
 
 `InterruptOnError` means that the Execution gets interrupted if any of the calls return with a status code >= 400, and the next Target will not be called anymore.
 
-The API documentation to create a target can be found [here](/apis/resources/action_service_v3/action-service-create-target)
+The API documentation to create a target can be found [here](/apis/resources/action_service_v3/zitadel-actions-create-target)
 
 ## Execution
 
@@ -65,7 +76,7 @@ The condition can be defined for 4 types of processes:
 - `Functions`, handling specific functionality in the logic of ZITADEL
 - `Events`, after a specific event happened and was stored in ZITADEL
 
-The API documentation to set an Execution can be found [here](/apis/resources/action_service_v3/action-service-set-execution)
+The API documentation to set an Execution can be found [here](/apis/resources/action_service_v3/zitadel-actions-set-execution)
 
 ### Condition Best Match
 
@@ -147,19 +158,19 @@ For Request and Response there are 3 levels the condition can be defined:
 - `All`, handling any request or response under the ZITADEL API
 
 The available conditions can be found under:
-- [All available Methods](/apis/resources/action_service_v3/action-service-list-execution-methods), for example `/zitadel.user.v2.UserService/AddHumanUser`
+- [All available Methods](/apis/resources/action_service_v3/zitadel-actions-list-execution-methods), for example `/zitadel.user.v2.UserService/AddHumanUser`
-- [All available Services](/apis/resources/action_service_v3/action-service-list-execution-services), for example `zitadel.user.v2.UserService`
+- [All available Services](/apis/resources/action_service_v3/zitadel-actions-list-execution-services), for example `zitadel.user.v2.UserService`
 
 ### Condition for Functions
 
 Replace the current Actions with the following flows:
 
-- [Internal Authentication](../actions/internal-authentication)
+- [Internal Authentication](/apis/actions/internal-authentication)
-- [External Authentication](../actions/external-authentication)
+- [External Authentication](/apis/actions/external-authentication)
-- [Complement Token](../actions/complement-token)
+- [Complement Token](/apis/actions/complement-token)
-- [Customize SAML Response](../actions/customize-samlresponse)
+- [Customize SAML Response](/apis/actions/customize-samlresponse)
 
-The available conditions can be found under [all available Functions](/apis/resources/action_service_v3/action-service-list-execution-functions).
+The available conditions can be found under [all available Functions](/apis/resources/action_service_v3/zitadel-actions-list-execution-functions).
 
 ### Condition for Events
 

docs/sidebars.js

@@ -745,10 +745,20 @@ module.exports = {
                 slug: "/apis/resources/action_service_v3",
                 description:
                   "This API is intended to manage custom executions and targets (previously known as actions) in a ZITADEL instance.\n" +
+                  "The version 3 of actions provide much more options to customize ZITADELs behaviour than previous action versions.\n" +
+                  "Also, v3 actions are available instance-wide, whereas previous actions had to be managed for each organization individually\n" +
+                  "ZITADEL doesn't restrict the implementation languages, tooling and runtime for v3 action executions anymore.\n" +
+                  "Instead, it calls external endpoints which are implemented and maintained by action v3 users.\n" +
                   "\n" +
                   "This project is in Preview state. It can AND will continue breaking until the services provide the same functionality as the current actions.",
               },
-              items: require("./docs/apis/resources/action_service_v3/sidebar.ts"),
+              items: [{
+                type: "doc",
+                id: "apis/actions/v3/usage",
+              }, {
+                type: "doc",
+                id: "apis/actions/v3/testing-locally",
+              }].concat(require("./docs/apis/resources/action_service_v3/sidebar.ts")),
             },
             {
               type: "category",
@@ -815,12 +825,6 @@ module.exports = {
         "apis/actions/objects",
       ],
     },
-    {
-      type: "category",
-      label: "Actions V2",
-      collapsed: false,
-      items: ["apis/actionsv2/introduction", "apis/actionsv2/execution-local"],
-    },
     {
       type: "doc",
       label: "gRPC Status Codes",

docs/vercel.json

@@ -24,6 +24,8 @@
         { "source": "/docs/apis/auth/:slug*", "destination": "/docs/apis/resources/auth/:slug*", "permanent": true },
         { "source": "/docs/apis/system/:slug*", "destination": "/docs/apis/resources/system/:slug*", "permanent": true },
         { "source": "/docs/apis/admin/:slug*", "destination": "/docs/apis/resources/admin/:slug*", "permanent": true },
+        { "source": "/docs/apis/actionsv2/introduction", "destination": "/docs/apis/actions/v3/usage", "permanent": true },
+        { "source": "/docs/apis/actionsv2/execution-local", "destination": "/docs/apis/actions/v3/testing-locally", "permanent": true },
         { "source": "/docs/guides/integrate/human-users", "destination": "/docs/guides/integrate/login", "permanent": true },
         { "source": "/docs/guides/solution-scenarios/device-authorization", "destination": "/docs/guides/integrate/login/oidc/device-authorization", "permanent": true },
         { "source": "/docs/guides/integrate/oauth-recommended-flows", "destination": "/docs/guides/integrate/login/oidc/oauth-recommended-flows", "permanent": true },