Learn the stack

Start with inspectFile, a capability: one named action with a contract and a server-side handler. The contract defines its name, input, output, failure, and metadata. The handler implements the action.

A service is a named interface for one job. A machine defines states and the events that permit movement between them. A projection builds a callable interface from capabilities.

Follow these parts, then try the hosted content tools.

Read Effect basics before this trace if the computation model is new. For implementation tasks, use services, Layer composition, and testing.

The pieces

• Effect describes work with typed failures and required dependencies.
• Schema defines accepted values and their runtime checks.
• A Layer builds services and supplies their construction dependencies.
• XState owns finite lifecycles. The Effect bridge runs their declared actors.
• TypeScript 7 and Effect diagnostics check types and Effect usage.
• Oxlint, Oxfmt, Vitest, and lefthook enforce the fence: checks and hooks that reject prohibited code and shortcuts.
• pnpm and Turborepo connect packages and cache checks.
• Alchemy declares the cloud. Follow learn Alchemy for the deployment graph.

One action, five interfaces

                     ┌─ CLI
                     ├─ HTTP
One Capability ──────┼─ MCP
                     ├─ code mode
                     └─ RPC

A projection exposes the same action through another interface. RPC serves browser clients. Code mode lets agents compose calls in one program.

All five interfaces use one handler.

Trace one action

The CLI uses inspectFile. The hosted site uses a separate content registry.

1. Define the contract

The contract names the action and its input, output, and failure schemas.

FileStatsError belongs to the interface. The annotations mark a repeatable, read-only action.

2. Bind one handler

implement binds the contract to runInspectMachine. The registry includes the resulting capability.

The handler starts a machine to read the file.

3. Put file work in a service

FileInspector.make captures the file system. Its inspect method reads bytes and maps file errors to FileStatsError.

The service exposes its Layer beside the implementation. This follows hexagonal architecture: composition supplies the file-system dependency.

Callers ask the service to inspect a path. Composition chooses the file-system implementation.

4. Give the lifecycle named states

A declared fromEffect actor calls FileInspector.

The machine starts in reading. It finishes in inspected or unreadable.

5. Project the registered actions

The command-line interface (CLI) projects the same capabilities list for each server interface.

The RPC projection derives contracts from its supplied capabilities.

A projection takes a registry and reuses its domain handlers.

6. Connect the CLI

toCommand derives each command. inspectFile also gets the stats alias.

The entry point supplies the service Layer and Node services. It denies approval by default.

The command keeps the shared handler.

7. Compose the cloud

An Alchemy Stack groups one cloud infrastructure program and its outputs. Alchemy declares the Stack, Cloudflare providers, and state. The Stack includes Mischief and Website.

The Stack deploys the cloud applications. The Node file-inspection CLI runs separately.

Try hosted search and read

Use POST /api/execute for code mode. The agent guide documents this search → read program:

const found = await tools.search({ query: "cartridges", limit: 1 });
const page = await tools.read({ id: found.matches[0].id });
return { title: page.title, id: page.id };

Send it as a JSON code string:

curl --request POST 'https://ratstack.sh/api/execute' \
  --header 'content-type: application/json' \
  --data '{"code":"const found = await tools.search({ query: \"cartridges\", limit: 1 }); const page = await tools.read({ id: found.matches[0].id }); return { title: page.title, id: page.id };"}'

read takes the exact ID from search. This hosted program reads site content.

Read before changing a piece

1. Read AGENTS.md for pins, boundaries, and the fence.
2. Read VISION.md for intent.
3. Read the package you plan to change.
4. Before Effect or XState work, read node_modules/effect/AGENTS.md and the pinned sources listed in repo law.

In a copied product repo, replace the template's product notes and rules. Keep the stack lessons that still serve the product.

Follow repo law and pinned code when an example is stale.

Pick the next skill

• Add schemas and a shared action: add-a-capability.
• Model a lifecycle: add a lifecycle machine.
• Remove an interface: keep or cut.
• Follow the cloud footprint: learn Alchemy.

Finish

Run the full gate:

pnpm turbo run check test build

Fix failures. Keep the fence intact.

Check deployment separately from the gate.