apps 0.0.1-beta.6 → 0.0.1-beta.60

package/README.md

@@ -4,10 +4,14 @@ Author apps with ordinary TypeScript and Promises. Framework operations use
 Effect v4 internally. The root export contains declarations and schemas;
 protocol helpers have separate entry points.
 
-The Executor package starts at `0.0.1-beta.0`. The first npm beta is being
-prepared; `latest` belongs to the earlier package and is not this framework.
-Once the beta is published, install it with `npm install --save-exact apps@beta`.
-For local testing, install the tarball made by `bun run pack` in this directory.
+Install the exact version your Executor host runs: agents read it with the
+Executor app's `framework.release`, and `executor apps framework` prints it. Run
+`npm install --save-exact apps@<version>` and declare the same version in the
+app's `package.json`. Do not install `apps@latest`; that tag is an unrelated,
+earlier package. The package includes `framework-reference.json`, generated from
+these declarations. The Executor app's `app-authoring` skill is the authoring
+guide; [Author an app](https://v2.executor.sh/docs/author-an-app) summarizes
+it. In this repository, `bun run pack` builds a local tarball.
 
 ```ts
 import { defineApp } from "apps";
@@ -21,12 +25,12 @@ export default defineApp({ accounts: {} }, async ({ signal }) => ({
 }));
 ```
 
-| Import           | Helper          | App dependency              |
-| ---------------- | --------------- | --------------------------- |
-| `apps/mcp`       | `mcpRouter`     | `@modelcontextprotocol/sdk` |
-| `apps/mcp/stdio` | `stdioRouter`   | `@modelcontextprotocol/sdk` |
-| `apps/graphql`   | `graphqlRouter` | `graphql`                   |
-| `apps/openapi`   | `openapiRouter` | None                        |
+| Import           | Helper                   | App dependency              |
+| ---------------- | ------------------------ | --------------------------- |
+| `apps/mcp`       | `mcpRouter`, `mcpHealth` | `@modelcontextprotocol/sdk` |
+| `apps/mcp/stdio` | `stdioRouter`            | `@modelcontextprotocol/sdk` |
+| `apps/graphql`   | `graphqlRouter`          | `graphql`                   |
+| `apps/openapi`   | `liveOpenapiRouter`      | None                        |
 
 MCP and GraphQL are optional peers. Subpath imports isolate their module graphs;
 optional peers keep unused libraries out of the dependency installation. The
@@ -80,6 +84,7 @@ export default defineApp(
       (account) =>
         mcpRouter({
           url: "https://example.com/mcp",
+          account,
           headers: { Authorization: "Bearer " + account.fields.token },
           signal,
         }),
@@ -89,8 +94,9 @@ export default defineApp(
 );
 ```
 
-MCP and GraphQL helpers accept `cache: ctx.cache.forAccount(account)` (or
-`ctx.cache` for a public source). They return a dynamic router, cache remote
+MCP and GraphQL helpers take the account their headers come from, and accept
+`cache: ctx.cache`; an account's catalog is kept in that account's scope and
+credentials never enter its key. They return a dynamic router, cache remote
 metadata, and compile only the selected tool. The defaults are five minutes fresh
 plus five minutes stale. Use `freshFor` / `staleFor` to change the windows, or
 `revalidate: true` to await a refresh. Tool results are never cached.
@@ -120,7 +126,8 @@ returns `approved`, `denied`, or `user-approval`. It receives `toolName`, decode
 `toolInput`, and `signal`. Reuse a policy function across tools or attach it when
 composing generated tools. There is no app-level policy.
 The framework enforces the decision before the selected tool body.
-Human approval delivery is separate; Executor SDK call/resume persists the pending invocation. See [tool approvals](../../notes/app-policies.md).
+Human approval delivery is separate; Executor SDK call/resume persists the pending invocation.
+See [Tools and approvals](https://v2.executor.sh/docs/concepts/tools-and-approvals).
 
 ## Browser UI
 
@@ -170,8 +177,7 @@ Use the Promise client methods for one-time reads and explicit writes.
 
 The product host supplies authentication and binds the browser to one configured
 app. No app ID, account token or Executor API key belongs in UI code. New
-activations reload open app pages. See [the full example](../../playground/demo-apps/live-inbox/ui/main.tsx)
-and [hosting notes](../../notes/app-ui.md).
+activations reload open app pages. The `live-inbox` example in `framework-reference.json` is a complete app with a UI.
 
 ## Webhooks
 
@@ -184,14 +190,13 @@ The SDK creates durable subscriptions with `executor.webhooks.create`. A
 subscription pins its deployment and saved account IDs while resolving fresh
 credentials on each invocation. `.many()` sources use one subscription per
 selected source account. Local, self-host and cloud use the same author API.
-See [the lifecycle and management API](../../notes/webhooks.md) and
-[the GitHub/Gmail example](../../playground/demo-apps/issue-mail/webhooks.ts).
+The app-authoring skill's `webhooks.md` covers the lifecycle and examples.
 
 Providers without a webhook API can use
 `setup: { instructions: "...", signingSecret: "executor" }`
 instead of `register` and `unregister`. The private setup page collects the
 `state` schema and the signing secret. Agents get a setup link and safe status
-through the normal management API. See [manual setup](../../notes/webhooks.md#manual-registration).
+through the normal management API.
 
 ## Workflows
 
@@ -205,9 +210,7 @@ Start and inspect runs through `executor.apps.workflowRuns`. Inside an app,
 queries can inspect `ctx.workflows`; mutations and webhooks can also start and
 terminate runs. Workflow execution has no live `elicit` capability.
 
-See [workflow semantics](../../notes/app-workflows.md) for replay, idempotency,
-self-host recovery and v1 limits, and the
-[repository report example](../../playground/demo-apps/workflow-report/) for a full app.
+The app-authoring skill's `workflows.md` covers replay, idempotency and limits.
 
 Local and self-host products run authored apps in Alchemy/workerd, using the
 same Worker build format and app-data facets as Cloud. Host filesystem and