@gjermundgaraba/effect-actions 0.1.0-rc.2 → 0.1.0

package/README.md

@@ -1,20 +1,10 @@
-# @gjermundgaraba/effect-actions
+# effect-actions
 
-Define an Effect action once, implement it once, and expose it through **HTTP, MCP, native Effect Toolkits, and CLIs**. Export an offline JSON catalog from the same contracts.
+Define an Effect action once. Serve it over HTTP and MCP, hand it to a model as a native
+Toolkit, run it from a CLI, and publish its contract as JSON. Same schemas, same handler,
+Effect's own servers and clients underneath.
 
-## Install
-
-```sh
-pnpm add @gjermundgaraba/effect-actions@rc effect@4.0.0-rc.116
-```
-
-For Node server wiring:
-
-```sh
-pnpm add @effect/platform-node@4.0.0-rc.116
-```
-
-## Quickstart
+## Looks like this
 
 ```ts
 import { McpProtocol } from "effect/unstable/ai";
@@ -48,297 +38,69 @@ export const routes = Layer.mergeAll(
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greetings/greet` and an
-MCP endpoint at `/mcp`. The HTTP response is `"Hello, Ada!"`; MCP returns
-`structuredContent: { value: "Hello, Ada!" }`; a declared error is an `isError` result
-whose text is the same JSON encoding HTTP sends as the body.
-See [examples/server.ts](examples/server.ts) for Node server wiring and the
-[authenticated demo](examples/README.md) for a runnable application.
-
-### Contracts
-
-- Omit `input` for an action without arguments.
-- `errors` is a list of failure schemas, defaulting to none. Each schema retains
-  its own `httpApiStatus` annotation.
-- A group's `errors` are added to every one of its actions, so a shared set, such as
-  authorization failures, is declared once. Its `schemaError` policy decides how HTTP
-  answers failed decoding or encoding; MCP keeps the native toolkit's answers. See
-  [schema-error policies](docs/behavior.md#schema-error-policies).
-- Actions default to both transports; use `http: false` or `mcp: false` to opt out.
-  Actions disabled on both remain available for explicitly mounted local CLI commands.
-- Action and group names match `[A-Za-z0-9_-]+` and are not `then`, which
-  would make a client thenable.
-- MCP input must have an object-root JSON Schema; the MCP adapter checks this at Layer
-  construction. HTTP allows scalar input. Results and errors may be any shape: MCP wraps
-  results as `{ value }` and reports errors as text, the protocol's own error channel.
-- `mcp.name` overrides the tool name (at most 128 characters). Tool hints default to
-  `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, and `openWorld: true`.
-  Hints do not enforce authorization, approval, or retries.
-- Schemas must be service-free. Handlers may require services.
-- The group name is the OpenAPI tag and operation-ID prefix (`greetings.greet`).
-
-## HTTP client
-
-Save the quickstart above as `quickstart.ts`. Once its routes are served:
-
-```ts
-import { HttpApiClient } from "effect/unstable/httpapi";
-import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
-import { Http } from "./quickstart.js";
-
-export const greeting = Effect.gen(function* () {
-  const client = yield* HttpApiClient.make(Http.api, { baseUrl: "http://127.0.0.1:3000" });
-
-  return yield* client.greetings.greet({ payload: { name: "Ada" } });
-}).pipe(Effect.provide(FetchHttpClient.layer));
-```
-
-Run `greeting` with `Effect.runPromise`. Use Effect's native `HttpApiClient.make(Http.api,
-options)`: methods are grouped by action group and take explicit `{ payload: ... }`
-arguments, including `{ payload: {} }` for no-input actions. Inputs and results are
-decoded values; MCP-only actions are excluded. HTTP paths include the group: `<apiPath>/<group>/<action>`.
-Authentication headers can be added with `transformClient`. See
-[client details](docs/behavior.md#http-client-details) for error types and response modes.
-
-## Multiple groups
-
-An application can split its contracts and handlers into groups without splitting its
-endpoints. Configuration comes first, then the groups or implementations:
-
-```ts
-import { McpProtocol } from "effect/unstable/ai";
-
-const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
-
-const routes = Layer.mergeAll(
-  Http.layer(PublicApp),
-  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
-  ActionMcp.layerHttp(
-    { protocols: [McpProtocol.v2026_07_28], name: "my-app", version: "1.0.0", path: "/mcp" },
-    UserApp,
-    AuditApp,
-  ),
-);
-```
-
-- **Explicit mounting.** `Http.layer(...apps)` registers the routes of the supplied groups, and router
-  middleware provided to a layer applies to that layer alone: above, only the user group
-  requires authentication. Use separate calls when groups need different middleware. A group that is never mounted has no routes.
-- **Each adapter reads only what it serves.** A group without HTTP actions registers nothing
-  and is not built by `Http.layer`, nor one without tools by `ActionMcp.layerHttp`.
-- **Names.** Routes are `POST /api/actions/<group>/<action>`, and native client methods
-  are `client.<group>.<action>({ payload: ... })`. Group names must be unique within
-  `ActionHttp.make`; action names need only be unique within their group. Tool names
-  must be unique within each Toolkit or MCP projection. Adapters validate the
-  namespaces they serve, not another transport's names.
-- **MCP middleware is per endpoint.** An MCP endpoint is one route, so middleware provided
-  to `ActionMcp.layerHttp`, authentication included, covers all of its tools. Handlers can still
-  authorize each tool differently. Only tools that need different middleware, such as none
-  at all, need their own endpoint: one `ActionMcp.layerHttp` per `path`.
-
-Each group is its own native `HttpApiGroup`, so a host can also combine separately made
-`Http.api` values with `HttpApi.addHttpApi`. See [examples/app.ts](examples/app.ts).
-
-## Serving the document
-
-`Http.api` is a native `HttpApi`, carrying every route, description, declared error and
-policy error. Documents and documentation UIs are therefore Effect's own:
+Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greetings/greet`
+and an MCP tool named `greet` at `/mcp`. The same `app` is also:
 
 ```ts
-import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
-import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
-
-const documentation = Layer.mergeAll(
-  HttpRouter.add("GET", "/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))),
-  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
-  HttpApiScalar.layer(Http.api, { path: "/reference" }),
-);
+const { toolkit, layer } = ActionToolkit.make(app); // native Effect AI Toolkit and its handler layer
+const cli = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
+const remote = ActionCliClient.command(Http, "greetings", "greet"); // same command, over HTTP
+const catalog = ActionCatalog.make(Actions); // offline JSON contract, no handlers acquired
 ```
 
-Each is an ordinary route layer, so it takes whatever middleware it is provided. The same
-value gives Effect's grouped client: `HttpApiClient.make(Http.api)`.
-
-## More projections
-
-The same implementation can be used without an HTTP server:
+And the client is Effect's own, typed from the same contract:
 
 ```ts
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
-import { Argument } from "effect/unstable/cli";
+const greeting = Effect.gen(function* () {
+  const client = yield* HttpApiClient.make(Http.api, { baseUrl });
 
-// Using Actions, Http, and app from the quickstart:
-const tools = ActionToolkit.make(app); // { toolkit, layer }, native Effect Toolkit
-const catalog = ActionCatalog.make(Actions); // JSON-serializable; no handlers acquired
-const command = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
-const local = ActionCli.command(app, "greet", {
-  parameters: { name: Argument.String("name") },
-  input: ({ name }) => ({ name }),
-}); // greet Ada
-const remote = ActionCliClient.command(Http, "greetings", "greet"); // host supplies HttpClient
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
+});
 ```
 
-- **Toolkit:** MCP-enabled actions become native tools with their declared names and
-  hints. Calls retain invocation-service requirements and return native results, not
-  MCP envelopes. See [examples/toolkit.ts](examples/toolkit.ts).
-- **MCP stdio:** `ActionMcp.layerStdio({ name, version, protocols }, ...apps)` runs a
-  subprocess server using a host-provided `Stdio` service and trusted process principal.
-  See [examples/mcp-stdio.ts](examples/mcp-stdio.ts). Stdout is protocol-only.
-- **Catalog:** standalone input/output/error JSON schemas with local `$defs`, plus
-  metadata and group-qualified identities. See [examples/catalog.ts](examples/catalog.ts).
-- **Local CLI:** `.command(app, "actionName", options?)` selects one action; `.group(app,
-options?)` selects a group, including local-only actions. The host supplies services.
-- **Remote CLI:** `ActionCliClient` projects HTTP contracts into commands using native
-  `HttpApiClient`; it never executes local handlers or manages credentials. See
-  [examples/cli.ts](examples/cli.ts) and [examples/cli-client.ts](examples/cli-client.ts).
-
-Generated CLI commands accept whole-input `--input '<json>'`. For a human-oriented
-command, supply native Effect flags/arguments through `parameters` and map them to
-encoded action input with `input`. Explicitly configured commands do not also accept
-`--input`; their syntax is independent of schema changes. Commands print validated
-JSON by default; an optional renderer enables human output with `--json` available.
-See [CLI boundaries](docs/behavior.md#cli-boundaries) for codecs and configuration.
+## Why
 
-## Adapter options
+- Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
+- A handler may fail only with the errors its action declares. Shared failures such as `Forbidden` are declared once on the group.
+- The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
+- Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
+- Tests run in memory. Call the routes through a web handler with the same typed client, or drive the official MCP client, without opening a port.
 
-| API                                    | Options                                                                  |
-| -------------------------------------- | ------------------------------------------------------------------------ |
-| `ActionGroup.make(options, …actions)`  | `name`, `errors`, `schemaError`                                          |
-| `ActionHttp.make(options, …groups)`    | `apiPath`                                                                |
-| `Http.layer(...apps)`                  | None                                                                     |
-| `ActionMcp.layerHttp(options, …apps)`  | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions` |
-| `ActionMcp.layerStdio(options, …apps)` | `name`, `version`, `protocols`, `instructions`                           |
-
-`apiPath` and MCP `path` have no defaults. `Http` has two members: `api` and `layer`. MCP `protocols` is required and takes Effect’s native `McpProtocol` adapters.
-Effect owns protocol negotiation and sessions.
-
-See [adapter behavior](docs/behavior.md) for shared schema-error policies,
-dependency lifetimes, wire formats, and MCP protocol support.
-
-## Scope
-
-HTTP means JSON POST endpoints, not Effect's RPC wire protocol. HTTP and MCP use
-Effect's servers: `HttpApi` and one `McpServer` `Tool` per action; there is no MCP SDK
-runtime dependency. Actions are unary:
-no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-
-Authentication and authorization belong to the application. Tool discovery is
-not filtered by actor. The example's bearer tokens are **demo-only**; production
-needs real token validation, MCP authorization discovery, request limits, and
-error reporting.
-
-## Development and packaging
-
-Requires a supported Node.js version (24 LTS recommended) and [Vite+](https://viteplus.dev).
+## Install
 
 ```sh
-vp install
-vp check
-vp test
-vp run test:package
-vp run example
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
 ```
 
-`vp run dev` watches the library build. `vp check` also verifies the compile-time
-assertions in `tests/types.spec.ts`. Tests cover both transports, official MCP clients,
-request-context handling, schema-error policies, and cancellation.
+Add `@effect/platform-node@4.0.0-rc.116` to serve from Node. Every module is a subpath import
+(`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle
+never loads a server.
 
-`vp run build` emits module-preserving ESM and declarations into `dist/`. The entry points
-are one subpath per module: `/Action`, `/ActionGroup`, `/ActionHttp`, `/ActionMcp`,
-`/ActionToolkit`, `/ActionCatalog`, `/ActionCli`, `/ActionCliClient`, `/Authentication`,
-`/Testing`, and `/TestingClient`. There is no package root, so a contracts-only or browser bundle never
-loads the MCP server or the optional client peer.
-`vp run test:package` builds and checks a tarball in an isolated consumer with
-`skipLibCheck: false`.
+## Docs
 
-## Authentication and OAuth discovery
+The reference in [docs/](docs/README.md) is written for coding agents: one card per module
+with the API, a canonical snippet, the rules, and the failure modes.
 
-`Authentication.middleware(CurrentActor, authenticate)` provides an application-defined
-context service for each request. `authenticate` is an Effect that succeeds with the
-identity or fails with the `HttpServerResponse` to send instead, so the host owns the
-status, body and any Bearer challenge: `HttpServerResponse.schemaJson(Unauthenticated)(error,
-{ status: 401, headers })`. Responses use `Cache-Control: no-store`, including failures handled
-by enclosing middleware. Provide the returned middleware's `.layer` to HTTP and MCP route
-layers. See [examples/app.ts](examples/app.ts).
+- [docs/README.md](docs/README.md): start here, includes the adapter decision list.
+- [docs/guarantees.md](docs/guarantees.md): cross-cutting rules for lifetimes, wire formats, and scope.
+- [docs/CONTEXT.md](docs/CONTEXT.md): the vocabulary the docs and the code use.
+- [examples/](examples/README.md): a runnable authenticated application with three groups, two MCP endpoints, OpenAPI, and every other projection.
 
-Use distinct service tags for startup capabilities and request identities. Never supply
-`CurrentActor` or other request-identity tags through startup layers or root context:
-native Effect context capture can shadow request values or supply missing runtime values.
-The adapters do not provide an additional context-isolation boundary.
+## For agents
 
-Authentication dependencies are request requirements, as with native `HttpRouter.middleware`.
-Use `.combine(...)` with middleware that provides them. Acquired resources stay alive
-until the request scope closes. Downstream action errors are handled by their transport,
-not serialized as authentication failures.
-
-`Authentication.protectedResource({ resource, authorizationServers, scopesSupported })`
-returns `{ layer, metadataUrl, challenge }`. Mount its public `layer` separately from
-protected routes. It publishes [RFC 9728 metadata](https://www.rfc-editor.org/rfc/rfc9728.html)
-at `/.well-known/oauth-protected-resource` followed by the resource path and query. Discovery
-matches that literal path and query for GET and HEAD; other requests reach the host router.
-Caching policy belongs to the host. `challenge()`
-returns the `WWW-Authenticate` value; pass `{ error: "invalid_token" }` or
-`{ error: "insufficient_scope", scope: "admin" }` where appropriate. Parameter values are
-quoted and escaped, never rejected. Supported scopes are advertised in metadata; the
-challenge names only scopes needed for that request. The helper publishes what it is given:
-your deployment is responsible for these being valid OAuth URLs (HTTPS, or loopback HTTP in
-development), and your application owns login, consent, and token verification.
-
-```ts
-const discovery = Authentication.protectedResource({
-  resource: "https://api.example.com/mcp",
-  authorizationServers: ["https://auth.example.com"],
-});
-
-// The response sent when authentication fails; the host owns status, body and challenge.
-const unauthenticated = HttpServerResponse.schemaJson(Unauthenticated)(
-  new Unauthenticated({ message: "A bearer token is required." }),
-  { status: 401, headers: { "www-authenticate": discovery.challenge({ error: "invalid_token" }) } },
-).pipe(Effect.orDie);
-
-const authentication = Authentication.middleware(
-  CurrentActor,
-  Effect.gen(function* () {
-    const actor = yield* verifyToken; // Effect<Option<Actor>, never, HttpServerRequest>
-
-    return Option.isNone(actor) ? yield* Effect.flip(unauthenticated) : actor.value;
-  }),
-);
-
-const routes = Layer.mergeAll(
-  discovery.layer,
-  protectedRoutes.pipe(Layer.provide(authentication.layer)),
-);
+```sh
+npx skills add gjermundgaraba/effect-actions --skill effect-actions
 ```
 
-## Testing
+The skill is generated from `docs/`, so pointing an agent at `docs/` (in this repository or
+in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
-Import from `@gjermundgaraba/effect-actions/Testing`; it requires no MCP client dependency.
-`withMcpClient` lives in `@gjermundgaraba/effect-actions/TestingClient` and needs the optional
-peer `@modelcontextprotocol/client@^2.0.0`. Only that entry point loads the peer.
-
-```ts
-const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
+## Status
 
-const greeting = Effect.gen(function* () {
-  const client = yield* httpClient(Http.api, web.handler);
+The `effect` peer is pinned to an exact Effect 4 release candidate and moves with it; expect a
+release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
-  return yield* client.greetings.greet({ payload: { name: "Ada" } });
-});
-```
+## Contributing
 
-- `httpClient(Http.api, handler, options?)` is the native grouped HTTP client calling a web handler in
-  memory. `options` are the client's connection options; `baseUrl` defaults to `http://localhost`.
-- `mcpRequest({ url, method, params?, headers? })` builds a stateless 2026-07-28 request.
-  `params` takes whatever `JSON.stringify` accepts, `undefined` fields included, so tests can
-  send malformed arguments.
-  Caller `params._meta` fields override the default client capabilities
-  and information; application metadata is preserved. The protocol version stays pinned to
-  2026-07-28 in both the request header and metadata. Metadata is merged shallowly.
-- `withMcpClient({ fetch, path, versionNegotiation?, baseUrl?, headers? }, async client => ...)`
-  connects the official client and closes it in a `finally` block.
-  `versionNegotiation` is passed directly to the official client (whose default is legacy).
-  For a stateless endpoint, pass `versionNegotiation: { mode: { pin: "2026-07-28" } }`.
+See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/docs/Action.md

@@ -0,0 +1,117 @@
+# Action
+
+One contract: a name, schemas for input, success and declared errors, and per-transport
+metadata. An action holds no behavior; handlers are bound by `ActionGroup.implement`.
+
+## API
+
+```ts
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+/** Any service-free schema. */
+type Codec = Schema.Codec<unknown, unknown, never, never>;
+
+function make<Name, Input = NoInput, Output, Errors = [], Http = true, Mcp = undefined>(
+  name: Name,
+  options: Options<Input, Output, Errors, Http, Mcp>,
+): Action<Name, Input, Output, Errors, Http, Mcp>;
+
+interface Options<Input, Output, Errors, Http, Mcp> {
+  readonly description: string;
+  readonly input?: Input; // omit for an action without arguments
+  readonly success: Output;
+  readonly errors?: Errors; // ReadonlyArray<Codec>; defaults to []
+  readonly http?: Http; // false hides the action from HTTP routes and clients
+  readonly mcp?: Mcp; // false hides the action from MCP; otherwise McpOptions
+}
+
+interface McpOptions {
+  readonly name?: string; // tool name; defaults to the action name; ^[A-Za-z0-9_-]{1,128}$
+  readonly readOnly?: boolean; // readOnlyHint, default false
+  readonly destructive?: boolean; // destructiveHint, default !readOnly
+  readonly idempotent?: boolean; // idempotentHint, default false
+  readonly openWorld?: boolean; // openWorldHint, default true
+}
+
+interface Action<Name, Input, Output, Errors, Http, Mcp> {
+  readonly name: Name;
+  readonly description: string;
+  readonly input: Input;
+  readonly success: Output;
+  readonly errors: Errors;
+  readonly http: Http;
+  readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld }; // resolved
+}
+
+/** Receives decoded input; may fail only with the declared errors. */
+type Handler<A extends Any, R = never> = (
+  input: A["input"]["Type"],
+) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
+
+type Any; // any action with its schemas erased
+```
+
+## Canonical
+
+```ts
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+  "UserNotFound",
+  { id: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+export const GetUser = Action.make("getUser", {
+  description: "Look up a user in your tenant.",
+  input: Schema.Struct({ id: Schema.String }),
+  success: Schema.Struct({ id: Schema.String, name: Schema.String }),
+  errors: [UserNotFound],
+  mcp: { name: "get_user", readOnly: true },
+});
+
+// No arguments: omit `input`. Identity comes from request context, never from input.
+export const WhoAmI = Action.make("whoAmI", {
+  description: "Inspect the authenticated actor.",
+  success: Schema.Struct({ id: Schema.String, tenantId: Schema.String }),
+  mcp: { readOnly: true },
+});
+
+// MCP-only: no HTTP route, no client method.
+export const ListChanges = Action.make("listChanges", {
+  description: "List renames in your tenant, oldest first.",
+  success: Schema.Struct({ changes: Schema.Array(Schema.String) }),
+  http: false,
+  mcp: { name: "list_changes", readOnly: true },
+});
+
+// Input decoding is the schema's: "21" on the wire, 21 in the handler.
+export const Double = Action.make("double", {
+  description: "Double a finite number supplied as a string.",
+  input: Schema.Struct({ value: Schema.FiniteFromString }),
+  success: Schema.Finite,
+  mcp: { readOnly: true },
+});
+```
+
+## Rules
+
+- Names match `[A-Za-z0-9_-]+`. `then` is rejected: it would make a client thenable.
+- Omit `input` for a no-argument action. The default is an empty object schema, which satisfies MCP's object-root requirement. Clients still pass `{ payload: {} }`.
+- `errors` is a list of schemas, default none. Each keeps its own `httpApiStatus` annotation; an unannotated error is served as HTTP 500. Group-level `errors` are appended to every action of the group (see [ActionGroup.md](ActionGroup.md)).
+- A handler may fail only with the declared errors. Anything else is a defect.
+- Both transports are on by default. `http: false` removes the route and the client method. `mcp: false` removes the tool. Both `false` makes a local-only action, reachable through `ActionCli` only.
+- MCP input must have an object-root JSON Schema. Scalar or array input is fine for HTTP, but `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, and `ActionToolkit.make` throw when called with such an action. Success and error schemas may be any shape.
+- `mcp.name` is the tool name, at most 128 characters, unique within the group and within any Toolkit or MCP projection that serves the group. Default is the action name.
+- Hint defaults: `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
+- Schemas must be service-free. Put service access in the handler.
+- The group name, not the action, is the OpenAPI tag and operation-ID prefix: `<group>.<action>`.
+- Object schemas strip excess fields on decode unless the schema is configured to reject them.
+
+## Failure modes
+
+- Throws at `make`: invalid name, name `then`, `mcp.name` longer than 128 characters or not matching the pattern.
+- Type error `Effect<..., X, ...> is not assignable` in `implement`: the handler fails with an undeclared error `X`. Add it to `errors` or handle it.
+- `<action>: MCP input must have an object root` thrown by `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, or `ActionToolkit.make`: an MCP-enabled action has non-object input. Wrap it in `Schema.Struct` or set `mcp: false`.
+- Handler receives a string where a number was expected: the schema is `Schema.String`, not a transforming codec such as `Schema.FiniteFromString`.

package/docs/ActionCatalog.md

@@ -0,0 +1,56 @@
+# ActionCatalog
+
+An offline JSON document describing groups: identities, metadata, and standalone JSON
+schemas. Built from contracts alone. No implementation, service, or server is involved.
+
+## API
+
+```ts
+import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+
+const make: (...groups: ReadonlyArray<ActionGroup.Any>) => Catalog;
+
+interface Catalog {
+  readonly version: "1";
+  readonly actions: ReadonlyArray<Entry>;
+}
+
+interface Entry {
+  readonly id: string; // "<group>.<action>"
+  readonly group: string;
+  readonly name: string;
+  readonly description: string;
+  readonly http: boolean;
+  readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld };
+  readonly input: JsonSchema.JsonSchema;
+  readonly success: JsonSchema.JsonSchema;
+  readonly errors: ReadonlyArray<JsonSchema.JsonSchema>; // own + inherited group errors
+  readonly httpSchemaErrors: ReadonlyArray<JsonSchema.JsonSchema>; // policy errors, HTTP only
+}
+```
+
+## Canonical
+
+```ts
+import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+import { AuditActions, PublicActions, UserActions } from "./contracts.js";
+
+const catalog = ActionCatalog.make(PublicActions, UserActions, AuditActions);
+
+process.stdout.write(JSON.stringify(catalog, null, 2));
+```
+
+## Rules
+
+- Takes groups, not implementations. Nothing is acquired or started.
+- `id` is the stable `<group>.<action>` identity, equal to the HTTP operation ID.
+- Schemas describe encoded action values: the JSON on the wire, not MCP's `{ value }` envelope and not deployment URLs.
+- Each schema owns its `$defs`. Equal schema identifiers in different entries never replace each other. Recursive references stay local to their schema.
+- `errors` includes group-level errors. HTTP schema-policy errors are listed separately in `httpSchemaErrors`.
+- Local-only actions (`http: false`, `mcp: false`) are included. Presence in a catalog is descriptive. It is not authorization, tool publication, or proof that a route is mounted. The host decides what to publish.
+- The package adds no search, no catalog HTTP endpoint, and no TypeScript code generation.
+
+## Failure modes
+
+- Type error passing an implementation: `make` takes groups. Pass `app.group` or the group value itself.
+- Consumers see `{ value }` in MCP responses but not in the catalog: expected. The catalog describes action values; MCP wraps them.

package/docs/ActionCli.md

@@ -0,0 +1,91 @@
+# ActionCli
+
+Native Effect CLI commands that run handlers in-process. The host provides every service;
+nothing is fetched over HTTP.
+
+## API
+
+```ts
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+
+/** One explicitly selected action. */
+const command: <G, Name extends G["actions"][number]["name"], H, EX, RX, Parameters = never>(
+  app: Implementation<G, H, EX, RX>,
+  name: Name,
+  options?: Options<SuccessType, Parameters>,
+) => Command.Command<string, never, {}, EX | SchemaError | DeclaredErrors, Exclude<RX | HandlerContext, Scope>>;
+
+/** Every action of the group, including local-only ones, under the group name. */
+const group: <G, H, EX, RX>(
+  app: Implementation<G, H, EX, RX>,
+  options?: GroupOptions,
+) => Command.Command<string, {}, {}, EX | SchemaError | DeclaredErrors, ...>;
+
+interface GroupOptions {
+  readonly name?: string; // override the group command name
+}
+
+type Options<Output, Parameters extends Command.Command.Config = never> =
+  | JsonOptions<Output>
+  | ParametersOptions<Output, Parameters>;
+
+interface JsonOptions<Output> {
+  readonly name?: string; // override the command name; default is the action name
+  readonly render?: (output: Output) => string; // human output; --json still prints JSON
+}
+
+interface ParametersOptions<Output, Parameters> {
+  readonly name?: string;
+  readonly render?: (output: Output) => string;
+  readonly parameters: Parameters; // native Effect Flag / Argument config
+  readonly input: (parsed: Command.Command.Config.Infer<Parameters>) => Schema.Json; // encoded action input
+}
+```
+
+## Canonical
+
+```ts
+import { Console, Effect, Logger } from "effect";
+import { Command, Flag } from "effect/unstable/cli";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { UserApp } from "./handlers.js";
+import { Users } from "./users.js";
+
+// Explicit syntax: `double --value 21`. No `--input` on this command.
+const command = ActionCli.command(UserApp, "double", {
+  parameters: { value: Flag.String("value") },
+  input: ({ value }) => ({ value }),
+});
+
+// Default syntax for a whole group: `users double --input '{"value":"21"}'`.
+const all = ActionCli.group(UserApp);
+
+Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
+  Effect.tapCause((cause) => Console.error(cause)),
+  Effect.provideService(Logger.LogToStderr, true),
+  Effect.provide(Users.layerMemory),
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain({ disableErrorReporting: true }),
+);
+```
+
+## Rules
+
+- `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `http: false` and `mcp: false`.
+- Default syntax is `--input '<json>'` carrying the entire encoded input: nested objects, arrays, scalars. Omitting `--input` supplies `{}`, which must still satisfy the input schema.
+- `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and no `--input`, so its syntax does not change when the schema changes.
+- `input(parsed)` returns encoded JSON. The action schema decodes it before dispatch; a mismatch is a `SchemaError` at runtime. Action fields are never turned into flags automatically.
+- Native `Flag` and `Argument` own names, aliases, ordering, defaults, and optionality. Use `Flag.optional` when omission must stay distinct from a default, and map the `Option` to a present or omitted field.
+- Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output; `--json` selects JSON again. Rendering cannot bypass validation.
+- Explicit flag names must not collide with the renderer's `--json` flag. A payload field named `json` is ordinary data; only the flag name is reserved.
+- Each invocation acquires the implementation in a scope and releases it after the call. Domain services and authority come from the host's provided layers. There is no HTTP fallback.
+- Group commands use the default JSON syntax. For a custom tree, compose individual `command` results with native `Command` combinators.
+
+## Failure modes
+
+- `SchemaError` on a valid-looking `--input`: the JSON is decoded input, so transforming codecs expect the encoded form (`"21"` for `FiniteFromString`, not `21`).
+- Command rejects `--input`: the command was built with `parameters`. Use its flags.
+- Type error: `name` is not an action of the group. Check `group.actions` names, not MCP tool names.
+- Handler cannot find a service: provide its Layer to the runtime (`Effect.provide`) before `runMain`. The command does not supply services.
+- `--json` flag conflict at definition: rename the native flag; the config property can keep its name.