@gjermundgaraba/effect-actions 0.4.1 → 0.5.0

package/dist/internal/cli.mjs

@@ -2,31 +2,45 @@ import { Console, Effect, Option, Schema } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 //#region src/internal/cli.ts
 const isParametersOptions = (options) => options?.parameters !== void 0;
-const jsonOutput = Flag.Boolean("json").pipe(Flag.optional, Flag.withDescription("Print machine-readable JSON"));
-const output = (action, execute, input, render, useJson) => Effect.gen(function* () {
+/**
+* A command with a renderer takes `--json` as a flag of its own, so nothing is
+* claimed tree-wide and a host's `--json`, global or not, is never contested.
+* Without a renderer the output is JSON already and there is no flag.
+*/
+const jsonFlag = Flag.Boolean("json").pipe(Flag.withDefault(false), Flag.withDescription("Print machine-readable JSON"));
+const output = (action, execute, input, render) => Effect.gen(function* () {
 	const value = yield* execute(input);
 	const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.success))(value);
-	const text = render !== void 0 && !useJson ? render(value) : JSON.stringify(encoded, null, 2);
-	yield* Console.log(text);
+	yield* Console.log(render === void 0 ? JSON.stringify(encoded, null, 2) : render(value));
 });
-const defaultCommand = (action, execute, options) => {
-	const input = Flag.String("input").pipe(Flag.withDefault("{}"), Flag.withSchema(Schema.fromJsonString(Schema.toCodecJson(action.input))), Flag.withDescription("Whole canonical action input as JSON"));
-	const config = options?.render === void 0 ? { input } : {
-		input,
-		output: { json: jsonOutput }
-	};
-	return Command.make(options?.name ?? action.name, config, (parsed) => Effect.gen(function* () {
-		const useJson = "output" in parsed && Option.isSome(parsed.output.json) && parsed.output.json.value === true;
-		return yield* output(action, execute, parsed.input, options?.render, useJson);
-	})).pipe(Command.withDescription(action.description));
+/**
+* One native command. The action's own parameters are one nested config, so the
+* flag added for a renderer never meets them in one record.
+*/
+const make = (action, execute, options, config, decode) => {
+	const name = options?.name ?? action.name;
+	const render = options?.render;
+	return (render === void 0 ? Command.make(name, { parameters: config }, ({ parameters }) => Effect.flatMap(decode(parameters), (input) => output(action, execute, input, void 0))) : Command.make(name, {
+		parameters: config,
+		json: jsonFlag
+	}, ({ parameters, json }) => Effect.flatMap(decode(parameters), (input) => output(action, execute, input, json ? void 0 : render)))).pipe(Command.withDescription(action.description));
 };
-const parametersCommand = (action, execute, options) => {
-	if (options.render === void 0) return Command.make(options.name ?? action.name, options.parameters, (parsed) => Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed)), (input) => output(action, execute, input, void 0, true))).pipe(Command.withDescription(action.description));
-	return Command.make(options.name ?? action.name, {
-		parameters: options.parameters,
-		output: { json: jsonOutput }
-	}, (parsed) => Effect.flatMap(Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed.parameters)), (input) => output(action, execute, input, options.render, Option.isSome(parsed.output.json) && parsed.output.json.value === true))).pipe(Command.withDescription(action.description));
+/**
+* The whole encoded input, inline or from a file. The native parser decodes both,
+* so an invalid value is rendered with the command's help wherever it came from.
+*/
+const inputFlags = (codec) => ({
+	input: Flag.String("input").pipe(Flag.withSchema(Schema.fromJsonString(codec)), Flag.optional, Flag.withDescription("Whole canonical action input as JSON")),
+	inputFile: Flag.FileSchema("input-file", codec, { format: "json" }).pipe(Flag.optional, Flag.withDescription("File containing the whole canonical action input as JSON"))
+});
+const defaultCommand = (action, execute, options) => {
+	const codec = Schema.toCodecJson(action.input);
+	return make(action, execute, options, inputFlags(codec), (parsed) => Option.match(Option.orElse(parsed.inputFile, () => parsed.input), {
+		onNone: () => Schema.decodeUnknownEffect(codec)({}),
+		onSome: Effect.succeed
+	}));
 };
+const parametersCommand = (action, execute, options) => make(action, execute, options, options.parameters, (parsed) => Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))(options.input(parsed)));
 /** Build one native command around an action-bound operation. */
 const command = (action, execute, options) => {
 	if (isParametersOptions(options)) return parametersCommand(action, execute, options);

package/dist/internal/implementation.d.mts

@@ -30,10 +30,21 @@ export declare class Implementation<G extends Actions, H, EX, RX> {
 }
 /** Any nominal implementation of `G`, with its record and channels erased. */
 export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
-/** Per-request requirements of one implementation, or of a union of them. */
-export type RequestContext<App> = App extends Implementation<any, infer H, any, any> ? HandlersContext<H> : never;
-/** Handler-acquisition failures of one implementation, or of a union of them. */
-export type BuildError<App> = App extends Implementation<any, any, infer EX, any> ? EX : never;
-/** Handler-acquisition requirements of one implementation, or of a union of them. */
-export type BuildContext<App> = App extends Implementation<any, any, any, infer RX> ? RX : never;
+/** The transports that serve a subset of a group's actions, by the contract flag that hides an action. */
+export type Transport = "http" | "mcp";
+/**
+ * Names of the actions of `G` that `T` may serve. Only an action hidden by a
+ * literal `false` is excluded; a flag decided at runtime keeps its requirements.
+ */
+export type ServedNames<G extends Actions, T extends Transport> = Exclude<G["actions"][number], T extends "http" ? {
+  readonly http: false;
+} : {
+  readonly mcp: false;
+}>["name"];
+/** Per-request requirements of the handlers `T` can invoke, or of a union of implementations. */
+export type RequestContext<App, T extends Transport> = App extends Implementation<infer G, infer H, any, any> ? { readonly [K in Extract<ServedNames<G, T>, keyof H>]: HandlerContext<H, K>; }[Extract<ServedNames<G, T>, keyof H>] : never;
+/** Handler-acquisition failures of the implementations `T` acquires, or of a union of them. */
+export type BuildError<App, T extends Transport> = App extends Implementation<infer G, any, infer EX, any> ? [ServedNames<G, T>] extends [never] ? never : EX : never;
+/** Handler-acquisition requirements of the implementations `T` acquires, or of a union of them. */
+export type BuildContext<App, T extends Transport> = App extends Implementation<infer G, any, any, infer RX> ? [ServedNames<G, T>] extends [never] ? never : RX : never;
 //#endregion

package/dist/internal/implementation.mjs

@@ -31,8 +31,16 @@ var Implementation = class Implementation {
 const dispatch = (group, action, handlers, before) => {
 	const handle = handlers[action.name];
 	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
+	const attributes = {
+		"action.group": group.name,
+		"action.name": action.name,
+		"action.access": action.access
+	};
 	return (input) => {
-		const handled = Effect.withSpan(Effect.suspend(() => handle(input)), `${group.name}.${action.name}`, { captureStackTrace: false });
+		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), attributes), `${group.name}.${action.name}`, {
+			captureStackTrace: false,
+			attributes
+		});
 		return before === void 0 ? handled : Effect.flatMap(before(action), () => handled);
 	};
 };

package/dist/internal/tools.d.mts

@@ -0,0 +1,22 @@
+import { Action_d_exports, Any, Codec } from "../Action.mjs";
+import "./implementation.mjs";
+import { Effect, Layer } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+//#region src/internal/tools.d.ts
+/** What a tool surface binds around the implementations it projects. */
+export interface SurfaceOptions<Errors extends ReadonlyArray<Codec>, R> {
+  /**
+   * Failures the surface answers with instead of a handler: authorization, rate
+   * limits. Declared on every tool, so a refusal is returned exactly like an
+   * action's own error.
+   */
+  readonly errors?: Errors;
+  /**
+   * Runs once per tool call, after the arguments are decoded and before the
+   * selected handler, with the action contract it is about to run. It fails with
+   * this surface's `errors`. Its services are request-time requirements, like a
+   * handler's.
+   */
+  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
+}
+//#endregion

package/dist/internal/tools.mjs

@@ -1,4 +1,4 @@
-import { projectedErrors } from "./actions.mjs";
+import { assertDistinct, projectedErrors } from "./actions.mjs";
 import { dispatch } from "./implementation.mjs";
 import { Effect, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
@@ -17,15 +17,6 @@ const entries = (apps) => apps.flatMap(({ app, actions }) => actions.map((action
 	app,
 	action
 })));
-/** Fail before acquiring handlers when two exposed tools share a name. */
-const assertDistinctToolNames = (tools) => {
-	const names = /* @__PURE__ */ new Set();
-	for (const { action } of tools) {
-		const name = action.mcp.name;
-		if (names.has(name)) throw new Error(`Duplicate MCP tool: ${name}`);
-		names.add(name);
-	}
-};
 const annotate = (tool, mcp) => tool.annotate(Tool.Readonly, mcp.readOnly).annotate(Tool.Destructive, mcp.destructive).annotate(Tool.Idempotent, mcp.idempotent).annotate(Tool.OpenWorld, mcp.openWorld);
 /**
 * A native Effect AI tool. Its schemas retain action transforms and its result
@@ -49,16 +40,10 @@ const mcpTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
 	failure: Schema.toCodecJson(Schema.Union(errors)),
 	failureMode: "return"
 }), action.mcp);
-/** MCP's input schema must describe a JSON object, including no-argument tools. */
-const assertMcpObjectInput = (action, tool) => {
-	const root = Tool.getJsonSchemaFromSchema(tool.parametersSchema);
-	if (root.$ref === void 0 && root.type !== "object") throw new Error(`${action.name}: MCP input must have an object root; omit input for no arguments`);
-};
 const project = (projection, entry, options) => {
 	const errors = projectedErrors(entry.action, options.errors);
 	const tool = projection === "native" ? nativeTool(entry.action, errors) : mcpTool(entry.action, errors);
 	if (projection === "native") return tool;
-	assertMcpObjectInput(entry.action, tool);
 	return tool.annotate(Tool.Strict, true);
 };
 const handler = (projection, app, action, handlers, before) => {
@@ -73,7 +58,7 @@ const handler = (projection, app, action, handlers, before) => {
 const bindTools = (apps, projection, options) => {
 	const served = toolApps(apps);
 	const selected = entries(served);
-	assertDistinctToolNames(selected);
+	assertDistinct("MCP tool", selected.map(({ action }) => action.mcp.name));
 	const toolkit = Toolkit.make(...selected.map((entry) => project(projection, entry, options)));
 	return {
 		toolkit,

package/docs/Action.md

@@ -5,56 +5,25 @@ metadata. An action holds no behavior; handlers are bound by `ActionGroup.implem
 
 ## 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 = [], Acc extends Access, Http = true, Mcp = undefined>(
-  name: Name,
-  options: Options<Input, Output, Errors, Acc, Http, Mcp>,
-): Action<Name, Input, Output, Errors, Acc, Http, Mcp>;
-
-/** What the action does to its resource. Authorization metadata, not an MCP hint. */
-type Access = "read" | "write";
-
-interface Options<Input, Output, Errors, Acc, 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 access: Acc; // required, no default
-  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 access === "read"
-  readonly destructive?: boolean; // destructiveHint, default !readOnly
-  readonly idempotent?: boolean; // idempotentHint, default false
-  readonly openWorld?: boolean; // openWorldHint, default true
-}
-
-interface Action<Name, Input, Output, Errors, Acc, Http, Mcp> {
-  readonly name: Name;
-  readonly description: string;
-  readonly input: Input;
-  readonly success: Output;
-  readonly errors: Errors;
-  readonly access: Acc; // the literal it was declared with
-  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
-```
+Import `@gjermundgaraba/effect-actions/Action`.
+
+| Export                                     | Purpose                                                                            |
+| ------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `make(name, options)`                      | Define a pure contract; literal names, access and transport exclusions stay typed. |
+| `Action`, `Any`, `Options`                 | Concrete contracts, erased contracts and construction options.                     |
+| `Codec`, `Handler`, `Access`, `McpOptions` | Service-free codecs, typed handlers, read/write classification and tool metadata.  |
+
+| Option                             | Meaning                                                                      |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| `description`, `success`, `access` | Required description, success codec and `"read"` / `"write"` classification. |
+| `input`                            | Optional codec; omission means an empty object.                              |
+| `errors`                           | Declared error codecs; defaults to none.                                     |
+| `http`                             | Defaults to enabled; `false` removes routes and client methods.              |
+| `mcp`                              | Defaults to enabled; `false` removes tools, otherwise accepts `McpOptions`.  |
+
+MCP options: `name` defaults to the action name; `readOnly` to `access === "read"`;
+`destructive` to `!readOnly`; `idempotent` to `false`; `openWorld` to `true`.
+Handlers receive decoded input and return decoded success, failing only with declared errors.
 
 ## Canonical
 
@@ -120,11 +89,11 @@ export const Double = Action.make("double", {
 - 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.
-- `access` is `"read"` or `"write"` and is required. `make` also checks it at runtime, so a caller the compiler never sees cannot define an action no rule classifies. It stays a literal on the action, so a rule may switch on it at the type level. It is authorization metadata for a surface's `before` hook (see [guarantees.md](guarantees.md)); the library itself authorizes nothing and no adapter reads it.
+- `access` is `"read"` or `"write"` and is required. `make` also checks it at runtime, so a caller the compiler never sees cannot define an action no rule classifies. It stays a literal on the action, so a rule may switch on it at the type level. It is authorization metadata for a surface's `before` hook (see [guarantees.md](guarantees.md)); the library itself authorizes nothing. Its only built-in uses are default MCP hints and span/log annotations; adapters never enforce an authorization rule from it.
 - `access` is independent of `mcp`. A local-only action (`mcp: false`) still has one, and an action may set `access: "write"` with `mcp: { readOnly: true }` if the tool hint should say something else. Derive authorization from `access`, never from a tool hint.
 - 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.
+- MCP input must have an object-root JSON Schema, an identified or recursive root included. Scalar or array input is fine for HTTP and for a native Toolkit, but the native MCP server refuses it when an `ActionMcp` layer is built. Success and error schemas may be any shape.
+- `mcp.name` is the tool name, matches `[A-Za-z0-9_-]+` except `then`, is 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: access === "read"`, `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>`.
@@ -134,7 +103,6 @@ export const Double = Action.make("double", {
 
 - Throws at `make`: invalid name, name `then`, an `access` that is neither `"read"` nor `"write"`, `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`.
 - `Property 'access' is missing` at `make`: every action declares `"read"` or `"write"`. There is no default.
 - A tool shows `readOnlyHint: false` for a read: the action sets `mcp: { readOnly: false }` explicitly, which wins over `access`.

package/docs/ActionCatalog.md

@@ -1,57 +1,54 @@
 # ActionCatalog
 
-An offline JSON document describing groups: identities, metadata, and standalone JSON
-schemas. Built from contracts alone. No implementation, service, or server is involved.
+An offline JSON document of contract identities, metadata and encoded-value JSON Schemas.
+Built from contracts alone: no implementation, service or server is involved.
 
 ## API
 
-```ts
-import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+Import `@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
-}
-```
+`make(...groups)` returns `Catalog`: `version: "3"` and an ordered `actions` array of `Entry`.
+
+| Entry field                          | Meaning                                                                      |
+| ------------------------------------ | ---------------------------------------------------------------------------- |
+| `id`, `group`, `name`, `description` | Stable `<group>.<action>` identity and contract metadata.                    |
+| `http`, `mcp`                        | HTTP enablement and resolved MCP enablement/name/hints.                      |
+| `input`, `success`                   | Standalone draft 2020-12 JSON Schema objects, not wrappers.                  |
+| `errors`                             | JSON Schema objects for own and inherited group errors.                      |
+| `httpSchemaErrors`                   | JSON Schema objects for HTTP policy errors; empty for HTTP-disabled actions. |
+
+Exported types are `Catalog` and `Entry`.
 
 ## Canonical
 
 ```ts
+import { NodeRuntime } from "@effect/platform-node";
+import { Console } from "effect";
 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));
+// Contract inspection requires no implementation or domain-service Layer.
+Console.log(
+  JSON.stringify(ActionCatalog.make(PublicActions, UserActions, AuditActions), null, 2),
+).pipe(NodeRuntime.runMain);
 ```
 
 ## Rules
 
 - Takes groups, not implementations. Nothing is acquired or started.
+- Group names must be unique. Entries preserve group declaration order, then action declaration order.
 - `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`. Surface errors are not listed: they belong to a binding, not to the contract.
-- `access` is not in the document. It is authorization metadata for a surface's hook, and the catalog is descriptive; read it from the contract (`group.actions`) when you need it.
-- 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.
+- Schemas describe encoded action values through native `Schema.toJsonSchemaDocument`, which lowers to the JSON codec first. A `Date` is a string, an `Option` a tagged union, a `bigint` a string of digits. These are action values, not MCP's `{ value }` envelope or deployment URLs.
+- JSON Schema does not preserve arbitrary Effect transformations or filters. Checks on the decoded side of a transformation, such as `FiniteFromString.check(isGreaterThan(0))`, are not described. The server's decode remains authoritative.
+- Each schema root includes its own `$schema` and, where needed, `$defs`. Equal identifiers across entries or fields cannot replace each other; recursive references resolve locally.
+- The catalog contains JSON Schema only. Use Effect's `SchemaRepresentation` directly when native schema persistence or revival is needed.
+- `errors` includes group-level errors. HTTP schema-policy errors are separate in `httpSchemaErrors`. Surface errors belong to bindings and are not listed.
+- `access` is omitted; read it from the contract when needed. Local-only actions are included. Presence grants no authorization or proof that an endpoint is mounted; the host decides what to publish.
+- No search, catalog HTTP endpoint, or TypeScript code generation is provided.
 
 ## 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.
+- `Duplicate catalog group: <name>`: two supplied groups share a name, including a group passed twice.
+- Type error passing an implementation: pass `app.group` or the group value itself.
+- Native JSON Schema conversion throws: the codec or its annotations cannot be converted.
+- JSON Schema accepts a value the server rejects: custom validation or a decoded-side check is not expressible in the wire schema. Server validation remains authoritative.

package/docs/ActionCli.md

@@ -5,47 +5,24 @@ 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, EB, RB, Parameters = never>(
-  app: Implementation<G, H, EX, RX>,
-  name: Name,
-  options?: Options<SuccessType, EB, RB, Parameters>,
-) => Command.Command<string, never, {}, EX | EB | SchemaError | DeclaredErrors, Exclude<RX | RB | HandlerContext, Scope>>;
-
-/** Every action of the group, including local-only ones, under the group name. */
-const group: <G, H, EX, RX, EB, RB>(
-  app: Implementation<G, H, EX, RX>,
-  options?: GroupOptions<EB, RB>,
-) => Command.Command<string, {}, {}, EX | EB | SchemaError | DeclaredErrors, ...>;
+Import `@gjermundgaraba/effect-actions/ActionCli`.
 
-/** The hook both projections accept. A CLI encodes nothing, so it declares no errors. */
-interface BeforeOptions<EB, RB> {
-  readonly before?: (action: Action.Any) => Effect.Effect<void, EB, RB>;
-}
+| API                            | Purpose                                                           |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `command(app, name, options?)` | One selected action as a native Effect `Command`.                 |
+| `group(app, options?)`         | Every action under a group command, including local-only actions. |
+| `Options`, `GroupOptions`      | Configuration for single and aggregate commands.                  |
 
-interface GroupOptions<EB, RB> extends BeforeOptions<EB, RB> {
-  readonly name?: string; // override the group command name
-}
+| Option                | Meaning                                                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `name`                | Override the command/group name.                                                                             |
+| `before`              | Hook receiving the selected `Action.Any`; its failures and services join the command's channels.             |
+| `render`              | Single command only: decoded success to human-readable string; adds `--json`.                                |
+| `parameters`, `input` | Single command only; supply together. Native flag/argument config and parsed-config-to-encoded-JSON mapping. |
 
-type Options<Output, EB, RB, Parameters extends Command.Command.Config = never> =
-  | (JsonOptions<Output> & BeforeOptions<EB, RB>)
-  | (ParametersOptions<Output, Parameters> & BeforeOptions<EB, RB>);
-
-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
-}
-```
+Without `parameters`/`input`, a command accepts `--input` and `--input-file`. Commands retain
+handler, builder and hook requirements/failures, plus codec failures. The invocation owns its
+scope. Success output is encoded; failures remain failures of the command Effect.
 
 ## Canonical
 
@@ -58,7 +35,6 @@ import { actors, authorize, CurrentActor } from "./auth.js";
 import { UserApp } from "./handlers.js";
 import { Users } from "./users.js";
 
-// Explicit syntax: `double --value 21`. No `--input` on this command.
 // The CLI binds the same hook as the servers; a local caller is not trusted more.
 const command = ActionCli.command(UserApp, "double", {
   parameters: { value: Flag.String("value") },
@@ -66,13 +42,10 @@ const command = ActionCli.command(UserApp, "double", {
   before: authorize,
 });
 
-// Default syntax for a whole group: `users double --input '{"value":"21"}'`.
-const all = ActionCli.group(UserApp, { before: authorize });
-
 Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
   Effect.tapCause((cause) => Console.error(cause)),
   Effect.provideService(Logger.LogToStderr, true),
-  // The hook runs here too, so a local caller supplies the identity it reads
+  // The hook runs here too, so a local caller supplies an identity for it
   // exactly as HTTP middleware does for a request.
   Effect.provideService(CurrentActor, actors.alice),
   Effect.provide(Users.layerMemory),
@@ -84,22 +57,22 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 ## 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.
+- Default syntax is `--input '<json>'` or `--input-file <path>` carrying the entire encoded input: nested objects, arrays, scalars. The file is read and JSON-parsed by the native `Flag.FileSchema`. Both are decoded by the native parser; if both are given, the file is used. Omitting both decodes `{}` separately on every invocation; result identity follows the codec's behavior. An action that requires input then fails with a `SchemaError`, exactly as a `parameters` command's mapped input does.
+- `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and neither `--input` nor `--input-file`, 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.
+- Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output and adds a `--json` flag to that command, which selects JSON again. Rendering cannot bypass validation.
+- `--json` is a regular flag of the rendered command only, placed after the command name on a `group` path. A command without `render` has no such flag: its output is JSON already. Nothing is declared tree-wide, so a host CLI may declare its own `--json`, global or not. A rendered `parameters` command reserves the flag name; a payload field named `json` is ordinary data.
 - 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.
 - `before` runs before the selected handler, on `command` and on every subcommand of `group`. Its failure joins the command's error channel and its services are the caller's to provide, so a local CLI supplies the identity the hook reads exactly as HTTP middleware does. A CLI is not a trusted bypass.
-- The CLI declares no `errors`: it encodes nothing, so a refusal is simply a typed failure of the command effect. The native parser also decodes `--input` before the command runs, so unlike HTTP the hook runs after input decoding.
+- The CLI declares no surface `errors`: it does not serialize failures, so a refusal is simply a typed failure of the command effect. Success values are still validated and encoded for output. The native parser also decodes `--input` and `--input-file` before the command runs, so invalid input skips the hook and handler.
 - 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.
+- Native `CliError.ShowHelp` containing `InvalidValue` for a supplied `--input` or `--input-file`: the parser rejected its JSON or schema before the command handler ran. Supply encoded input (`"21"` for `FiniteFromString`, not `21`). With neither flag, decoding the default `{}` can fail with `SchemaError`; so can a `parameters` command's mapped input or an invalid success value.
+- Command rejects `--input` or `--input-file`: 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.
-- A command requires a request-identity tag no handler yields: the `before` hook yields it. Provide it, or build the command without a hook for local use.
-- `--json` flag conflict at definition: rename the native flag; the config property can keep its name.
+- A command requires a request-identity tag no handler yields: the `before` hook yields it. Provide a trusted identity around the invocation; do not remove the authorization hook just to satisfy the service requirement.
+- `--json` flag conflict at definition on a rendered `parameters` command: rename the native flag; the config property can keep its name.

package/docs/ActionCliClient.md

@@ -5,37 +5,22 @@ handler locally and manages no credentials.
 
 ## API
 
-```ts
-import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
-
-/** One HTTP-enabled action retained by the binding. */
-const command: <const Groups, const GroupName, const ActionName, Parameters = never>(
-  http: Http<Groups>,
-  groupName: GroupName,
-  actionName: ActionName, // only actions with http: true
-  options?: Options<SuccessType, Parameters>,
-) => Command.Command<string, never, {}, ClientErrors, HttpClient.HttpClient | ClientServices>;
+Import `@gjermundgaraba/effect-actions/ActionCliClient`.
 
-/** Every HTTP-enabled action of one group under the group name. */
-const group: <const Groups, const GroupName>(
-  http: Http<Groups>,
-  groupName: GroupName,
-  options?: GroupOptions,
-) => Command.Command<string, {}, {}, ClientErrors, HttpClient.HttpClient | ClientServices>;
+| API                                              | Purpose                                                                    |
+| ------------------------------------------------ | -------------------------------------------------------------------------- |
+| `command(http, groupName, actionName, options?)` | Call one HTTP-enabled action through a native Effect `Command`.            |
+| `group(http, groupName, options?)`               | Every HTTP-enabled action of a bound group under one command.              |
+| `Options`, `GroupOptions`, `Connection`          | Single/aggregate command configuration and native HTTP connection options. |
 
-type Options<Output, Parameters> = ActionCli.Options<Output, Parameters> & {
-  /** Passed directly to HttpApiClient.make: baseUrl, transformClient, transformResponse. */
-  readonly connection?: Parameters<typeof HttpApiClient.make>[1];
-};
-
-interface GroupOptions {
-  readonly name?: string;
-  readonly connection?: Parameters<typeof HttpApiClient.make>[1]; // shared by every action
-}
-```
+Single-command options: `name`, `render`, paired `parameters`/`input`, and `connection`.
+Group options: `name` and `connection`. Parsing/rendering semantics match [ActionCli.md](ActionCli.md).
+`connection` accepts native `HttpApiClient.make` configuration, including `baseUrl`,
+`transformClient` and `transformResponse`.
 
-Parsing and rendering options (`name`, `render`, `parameters`, `input`) are the same as
-[ActionCli.md](ActionCli.md).
+Remote commands have no local `before` hook: the server owns authorization. Their Effects
+retain the selected endpoint's client failures and middleware requirements, and require an
+`HttpClient` supplied by the host. Group/action selectors stay checked against the bound API.
 
 ## Canonical
 
@@ -53,7 +38,8 @@ const command = ActionCliClient.command(Http, "public", "status", {
 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(NodeHttpClient.layerUndici), // the host supplies HttpClient
+  // The host supplies the native client and its connection configuration.
+  Effect.provide(NodeHttpClient.layerUndici),
   Effect.provide(NodeServices.layer),
   NodeRuntime.runMain({ disableErrorReporting: true }),
 );
@@ -66,7 +52,7 @@ Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClient
 - Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group with `http: true`. Runtime guards reject dynamically supplied strings that the types would not accept.
 - The host provides `HttpClient` and its configuration. Endpoint selection, credentials, and storage are the host's; nothing is inferred from action arguments.
 - Input is decoded by the action schema before dispatch, then passed to the native client at its normal codec boundary. Do not pre-encode values.
-- Output is validated and printed as JSON, or through `render` with `--json` available, exactly as in `ActionCli`.
+- Input syntax (`--input`, `--input-file`, or `parameters`) and output (`render` and its `--json` flag) are exactly as in `ActionCli`.
 - Errors are the client's: declared errors, policy errors, `SchemaError`, and `HttpClientError`.
 
 ## Failure modes