For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

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.¶

export const inspectFileContract = defineContract("inspectFile", {
  annotations: { idempotent: true, readOnly: true },
  description: "Count bytes, characters, words, and lines in a file",
  failure: FileStatsError,
  input: Schema.Struct({
    path: Schema.String.annotate({ description: "File to inspect" }),
  }),
  output: FileStatsSchema,
});

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²⁷.¶

export const inspectFile = implement(inspectFileContract, ({ path }) =>
  runInspectMachine(path)
);

export const capabilities = [
  inspectFile,
  ...flagCapabilities,
  joinInterest,
  listPrompts,
  getPrompt,
  listCafeNews,
  listCafeProjects,
] as const;

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.¶

  make: Effect.gen(function* makeFileInspector() {
    const fileSystem = yield* FileSystem.FileSystem;

    const inspect = Effect.fn("FileInspector.inspect")(function* inspect(
      path: string
    ) {
      const content = yield* fileSystem
        .readFile(path)
        .pipe(
          Effect.mapError(
            (error) => new FileStatsError({ path, reason: error.message })
          )
        );

      return summarizeBytes(path, content);
    });

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

    return { inspect } as const;
  }),
}) {
  static readonly layer = Layer.effect(this, this.make);
}

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

4. Give the lifecycle named states

A declared createEffectLogic actor calls FileInspector.¶

const readStats = createEffectLogic({
  effect: ({ input }) =>
    FileInspector.use((inspector) => inspector.inspect(input.path)),
  schemas: { input: Schema.Struct({ path: Schema.String }) },
});

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

  initial: "reading",
  output: ({ context }) => context.outcome,
  states: {
    inspected: { type: "final" },
    reading: {
      invoke: {
        input: ({ context }) => ({ path: context.path }),
        onDone: {
          context: ({ event }) => ({
            outcome: inspectOutcome.Inspected({ stats: event.output }),
          }),
          target: "inspected",
        },
        onError: {
          context: ({ event }) => ({
            outcome: inspectOutcome.Unreadable({ error: event.error }),
          }),
          target: "unreadable",
        },
        src: "readStats",
      },
    },
    unreadable: { type: "final" },
  },
});

5. Project the registered actions

The command-line interface (CLI) projects capability lists for each server interface. HTTP uses stateless learning capabilities. MCP and code mode²¹ use their local learning counterparts. All three include inspectFile.¶

export const capabilities = [
  ...coreCapabilities,
  ...learnCapabilities,
] as const;

export const cliCapabilities = [
  ...coreCapabilities,
  ...localLearnCapabilities,
] as const;
export const http = toHttpApi("RatStack", capabilities);

export const tools = toToolkit(cliCapabilities);

export const codeMode = toCodeMode(cliCapabilities);

export const routes = Layer.merge(
  HttpApiBuilder.layer(http.api, { openapiPath: "/openapi.json" }).pipe(
    Layer.provide(http.layer)
  ),
  HttpApiScalar.layer(http.api, { path: "/docs" })
);

The RPC projection¹⁸ derives contracts from its supplied capabilities.¶

export const toRpc = <const Caps extends readonly AnyCapability[]>(
  capabilities: Caps
): RpcProjection<Caps> => {
  const contracts = capabilities.map((capability) => capability.contract);

A projection takes a registry and reuses its domain handlers.¶

6. Connect the CLI

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

const capabilityCommands = commandCapabilities.map((capability) => {
  const command =
    capability === inspectFile
      ? toCommand(capability, {
          positional: ["path"],
          render: formatFileStats,
        }).pipe(Command.withAlias("stats"))
      : toCommand(
          capability,
          capability === setFlag ? { promptForApproval: true } : undefined
        );

  return command;
});

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

  Effect.provide(
    Layer.mergeAll(
      Layer.provideMerge(FileInspector.layer, NodeServices.layer),
      remoteJoinInterestLayer,
      localPromptLibraryLayer.pipe(Layer.provide(NodeServices.layer)),
      localCafeDirectoryLayer.pipe(Layer.provide(NodeServices.layer)),
      localLearnLayer,
      Flags.defaults(eventFlags),
      Approval.denyAll
    )
  )

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.¶

export default Alchemy.Stack(
  "RatStack",
  {
    providers: Layer.mergeAll(Cloudflare.providers(), Drizzle.providers()),
    state: Cloudflare.state(),
  },
  Effect.gen(function* stack() {
    const website = yield* Website;

    const mischief = yield* Mischief;

    yield* mischief.bind`${website}`({
      bindings: [
        { name: "WEBSITE", service: website.workerName, type: "service" },
      ],
    });

    return { mischiefUrl: mischief.url, websiteUrl: website.url };
  }).pipe(

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.¶

Last changed 2026-10-18 in e5c3077. Source on GitHub. Change log.

Content updated 2026-10-06.