UsefulSoftwareCo · RhysSullivan · May 16, 2026 · May 16, 2026 · May 16, 2026
diff --git a/bun.lock b/bun.lock
diff --git a/docs/cloud/api-keys.mdx b/docs/cloud/api-keys.mdx
@@ -0,0 +1,6 @@
+---
+title: API Keys
+description: Authenticate to Executor Cloud.
+---
+
+This page will document cloud API key creation, rotation, and usage once the public flow is finalized.
diff --git a/docs/cloud/hosting-model.mdx b/docs/cloud/hosting-model.mdx
@@ -0,0 +1,6 @@
+---
+title: Hosting Model
+description: Understand what runs in Executor Cloud.
+---
+
+This page will describe the hosted runtime boundaries for Executor Cloud.
diff --git a/docs/cloud/overview.mdx b/docs/cloud/overview.mdx
@@ -0,0 +1,6 @@
+---
+title: Overview
+description: Understand Executor Cloud.
+---
+
+Executor Cloud provides hosted workspaces for shared sources, credentials, policies, and agent access.
diff --git a/docs/cloud/sources.mdx b/docs/cloud/sources.mdx
@@ -0,0 +1,6 @@
+---
+title: Sources
+description: Manage hosted source connections.
+---
+
+Cloud sources make shared tools available to the agents and applications connected to a workspace.
diff --git a/docs/cloud/workspaces.mdx b/docs/cloud/workspaces.mdx
@@ -0,0 +1,6 @@
+---
+title: Workspaces
+description: Organize shared Executor resources.
+---
+
+Workspaces group sources, policies, and credentials for a team or application.
diff --git a/docs/concepts/connections.mdx b/docs/concepts/connections.mdx
@@ -0,0 +1,8 @@
+---
+title: Connections
+description: OAuth and provider-backed credentials connected to Executor.
+---
+
+Connections represent authenticated relationships with external providers.
+
+Use connections when a source needs provider-managed credentials, OAuth refresh behavior, or an identity label that users can recognize and manage separately from bare secrets.
diff --git a/docs/concepts/executor.mdx b/docs/concepts/executor.mdx
@@ -0,0 +1,6 @@
+---
+title: Executor
+description: The runtime that connects sources, tools, auth, and policy.
+---
+
+An Executor is the runtime surface that applications and agents use to discover tools, inspect schemas, invoke tools, and resolve credentials.
diff --git a/docs/concepts/policies.mdx b/docs/concepts/policies.mdx
@@ -0,0 +1,6 @@
+---
+title: Policies
+description: Control which tools can run.
+---
+
+Policies decide whether tool invocations are allowed, blocked, or require approval.
diff --git a/docs/concepts/scopes.mdx b/docs/concepts/scopes.mdx
@@ -0,0 +1,6 @@
+---
+title: Scopes
+description: Resource ownership and precedence.
+---
+
+Scopes describe where resources belong and how Executor resolves resources across user, workspace, or organization boundaries.
diff --git a/docs/concepts/secrets.mdx b/docs/concepts/secrets.mdx
@@ -0,0 +1,6 @@
+---
+title: Secrets
+description: Credential references shared by sources and tools.
+---
+
+Secrets store credentials separately from source definitions so tools can authenticate without exposing sensitive values.
diff --git a/docs/concepts/sources.mdx b/docs/concepts/sources.mdx
@@ -0,0 +1,6 @@
+---
+title: Sources
+description: External systems connected to Executor.
+---
+
+A source is an external system or protocol endpoint that contributes tools to Executor.
diff --git a/docs/concepts/tools.mdx b/docs/concepts/tools.mdx
@@ -0,0 +1,6 @@
+---
+title: Tools
+description: Callable actions exposed by sources.
+---
+
+A tool is a typed callable action with metadata, input schema, and invocation behavior.
diff --git a/docs/docs.json b/docs/docs.json
@@ -0,0 +1,93 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "aspen",
+  "name": "Executor",
+  "colors": {
+    "primary": "#009f83",
+    "light": "#009f83",
+    "dark": "#6ee7c8"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Getting Started",
+        "groups": [
+          {
+            "group": "Start Here",
+            "pages": [
+              "index",
+              "getting-started/overview",
+              "getting-started/local",
+              "getting-started/cloud",
+              "getting-started/sdk"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Concepts",
+        "groups": [
+          {
+            "group": "Core Concepts",
+            "pages": [
+              "concepts/executor",
+              "concepts/sources",
+              "concepts/tools",
+              "concepts/scopes",
+              "concepts/policies",
+              "concepts/secrets",
+              "concepts/connections"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "SDK",
+        "groups": [
+          {
+            "group": "SDK",
+            "pages": [
+              "sdk/quickstart",
+              "sdk/create-executor",
+              "sdk/sources",
+              "sdk/tools",
+              "sdk/secrets",
+              "sdk/approvals",
+              "sdk/errors"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Local",
+        "groups": [
+          {
+            "group": "Local Product",
+            "pages": [
+              "local/install",
+              "local/web-ui",
+              "local/mcp-server",
+              "local/cli",
+              "local/auth-and-secrets"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Cloud",
+        "groups": [
+          {
+            "group": "Cloud Product",
+            "pages": [
+              "cloud/overview",
+              "cloud/workspaces",
+              "cloud/sources",
+              "cloud/api-keys",
+              "cloud/hosting-model"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/docs/getting-started/cloud.mdx b/docs/getting-started/cloud.mdx
@@ -0,0 +1,8 @@
+---
+title: Cloud Quickstart
+description: Start with Executor Cloud.
+---
+
+Use Executor Cloud when your team needs shared workspaces, hosted source management, and centralized credentials.
+
+This page will be filled in as the cloud onboarding flow stabilizes.
diff --git a/docs/getting-started/local.mdx b/docs/getting-started/local.mdx
@@ -0,0 +1,8 @@
+---
+title: Local Quickstart
+description: Start Executor locally.
+---
+
+Use the local product when you want Executor running on your machine with a web UI, CLI, and MCP server for local agents.
+
+This page will be backed by a smoke-tested local workflow.
diff --git a/docs/getting-started/overview.mdx b/docs/getting-started/overview.mdx
@@ -0,0 +1,10 @@
+---
+title: Overview
+description: Choose the right Executor entrypoint.
+---
+
+Executor has three main entrypoints:
+
+- Local product: run Executor on your machine and connect agents through MCP or the CLI.
+- Cloud product: manage hosted workspaces, shared sources, and team-facing auth.
+- SDK: embed Executor in your own TypeScript application through `@executor-js/sdk`.
diff --git a/docs/getting-started/sdk.mdx b/docs/getting-started/sdk.mdx
@@ -0,0 +1,8 @@
+---
+title: SDK Quickstart
+description: Embed Executor with the SDK.
+---
+
+Use the SDK when you want to create an Executor instance inside your own TypeScript application.
+
+All examples on this path should import the Executor API from `@executor-js/sdk`.
diff --git a/docs/index.mdx b/docs/index.mdx
@@ -0,0 +1,8 @@
+---
+title: Executor
+description: Product and SDK documentation for Executor.
+---
+
+Executor gives AI agents one shared tool catalog, auth layer, and policy system across local, cloud, and SDK workflows.
+
+These docs are scaffolded around realistic examples. SDK examples should compile against the public SDK packages before their snippets graduate into guide content.
diff --git a/docs/local/auth-and-secrets.mdx b/docs/local/auth-and-secrets.mdx
@@ -0,0 +1,6 @@
+---
+title: Auth And Secrets
+description: Manage local credentials.
+---
+
+This page will explain how local credentials are stored, resolved, and used by sources.
diff --git a/docs/local/cli.mdx b/docs/local/cli.mdx
@@ -0,0 +1,6 @@
+---
+title: CLI
+description: Use Executor from the command line.
+---
+
+The CLI starts local services, inspects tools, invokes tools, and manages runtime workflows.
diff --git a/docs/local/install.mdx b/docs/local/install.mdx
@@ -0,0 +1,6 @@
+---
+title: Install
+description: Install and start Executor locally.
+---
+
+This page will cover local installation and startup commands.
diff --git a/docs/local/mcp-server.mdx b/docs/local/mcp-server.mdx
@@ -0,0 +1,6 @@
+---
+title: MCP Server
+description: Connect local agents to Executor through MCP.
+---
+
+Executor can run as an MCP server so compatible agents can use the same shared tool catalog.
diff --git a/docs/local/web-ui.mdx b/docs/local/web-ui.mdx
@@ -0,0 +1,6 @@
+---
+title: Web UI
+description: Manage sources, tools, secrets, and policies locally.
+---
+
+The local web UI is the fastest way to configure Executor on your machine.
diff --git a/docs/sdk/approvals.mdx b/docs/sdk/approvals.mdx
@@ -0,0 +1,6 @@
+---
+title: Approvals
+description: Handle approval and elicitation requests.
+---
+
+Approvals let a tool ask for confirmation or additional input while it is being invoked.
diff --git a/docs/sdk/create-executor.mdx b/docs/sdk/create-executor.mdx
@@ -0,0 +1,6 @@
+---
+title: Create An Executor
+description: Configure scopes, plugins, storage, and elicitation.
+---
+
+This page will explain the public `createExecutor` flow.
diff --git a/docs/sdk/errors.mdx b/docs/sdk/errors.mdx
@@ -0,0 +1,6 @@
+---
+title: Errors
+description: Handle SDK failures.
+---
+
+This page will document the public error behavior exposed by `@executor-js/sdk`.
diff --git a/docs/sdk/quickstart.mdx b/docs/sdk/quickstart.mdx
@@ -0,0 +1,70 @@
+---
+title: Quickstart
+description: Create an Executor, add a source, and inspect its tools.
+---
+
+import CreateExecutor from "/snippets/sdk/quickstart/create-executor.mdx";
+import AddSource from "/snippets/sdk/quickstart/add-source.mdx";
+import ListTools from "/snippets/sdk/quickstart/list-tools.mdx";
+import InspectSchema from "/snippets/sdk/quickstart/inspect-schema.mdx";
+import CloseExecutor from "/snippets/sdk/quickstart/close-executor.mdx";
+
+{/* Code snippets on this page are generated from examples/docs-sdk-quickstart/src/main.ts. */}
+
+The SDK lets you embed Executor in a TypeScript application.
+
+This quickstart creates an Executor, loads an OpenAPI source from a local spec, lists the tools it contributed, and inspects one tool schema. The snippets on this page are generated from a runnable example in `examples/docs-sdk-quickstart`.
+
+## Install
+
+<CodeGroup>
+
+```bash npm
+npm install @executor-js/sdk @executor-js/plugin-openapi
+```
+
+```bash pnpm
+pnpm add @executor-js/sdk @executor-js/plugin-openapi
+```
+
+```bash yarn
+yarn add @executor-js/sdk @executor-js/plugin-openapi
+```
+
+```bash bun
+bun add @executor-js/sdk @executor-js/plugin-openapi
+```
+
+</CodeGroup>
+
+## Create An Executor
+
+Import the SDK and configure the plugins you want to expose.
+
+<CreateExecutor />
+
+`onElicitation: "accept-all"` is convenient for scripts and examples. Applications with interactive approval flows should pass a handler instead.
+
+## Add A Source
+
+Sources add tools to the Executor catalog. This example registers an OpenAPI document under the `inventory` namespace.
+
+<AddSource />
+
+## List Tools
+
+After a source is registered, its tools appear in the unified tool catalog.
+
+<ListTools />
+
+## Inspect A Tool
+
+Tools expose schema metadata that agents and applications can use before invoking them.
+
+<InspectSchema />
+
+## Shut Down
+
+Close the Executor when your process is done with it.
+
+<CloseExecutor />
diff --git a/docs/sdk/secrets.mdx b/docs/sdk/secrets.mdx
@@ -0,0 +1,6 @@
+---
+title: Secrets
+description: Store and reference credentials from SDK workflows.
+---
+
+Secrets let sources and tools use credentials without hard-coding sensitive values in source definitions.
diff --git a/docs/sdk/sources.mdx b/docs/sdk/sources.mdx
@@ -0,0 +1,6 @@
+---
+title: Sources
+description: Add MCP, OpenAPI, GraphQL, and other sources.
+---
+
+Sources turn external systems into tools that agents can discover and call.