# Agent instructions

## Release and cleanup

Publish exclusively through `.github/workflows/release.yml` with GitHub OIDC.
The package release scripts are workflow entrypoints: never publish locally,
request npm publishing tokens/login, or troubleshoot local publishing auth.
Use the existing Changesets flow and verify Actions plus the registry before
updating installations.

Delete unused code, scripts, duplicate workarounds, and legacy installs after
checking active owners/references. Preserve auth, operator env, durable data,
and intentional duplicate suppression. Prefer existing helpers, stdlib, and
native features over new wrappers or fallback frameworks.

## Build and check

- `pnpm run build` compiles one composite plugin root (`artifact/`: the
  Claude, Codex, Cursor, and Agent Plugins `portable` projections over one
  set of files, `agent-bundle.manifest.json` beside `bin/`) and the package
  binaries (`dist/bin/hauler.js`, `dist/bin/cargo-hauler.mjs`,
  `dist/bin/cargo-hauler-install.js`).
- Commit `artifact/` and the repository-root `.claude-plugin/`,
  `.agents/plugins/`, and `.cursor-plugin/` marketplace manifests generated by
  that build. GitHub installs read them without building source. Never
  hand-edit generated outputs; `pnpm validate:artifact` verifies the root.
- `pnpm run check` is the gate: verify committed artifact freshness and bytes
  before any build, validate, build, typecheck, Effect
  diagnostics, `rstest`, the route-unit suite, and browser App tests. Run it
  before claiming a change is done.
- The plugin surface is an agent-bundle application: `src/layout.tsx` (the
  shell), `src/providers/hauler-daemon.ts` (daemon connection),
  `src/internal/ui/documents` (typed components over `view-models.ts`), `src/mcp/hauler/tools` and
  `src/mcp/hauler/apps` (MCP; each tool's `<tool>.cli.ts` is its `hauler`
  command), `src/events` (hook routes; `tool/before.ts` and
  `tool/after.ts` decide on the raw command before their `.view.tsx` modules
  load — keep the handlers free of React and Effect), `src/internal/host-hooks` (the
  handlers the routes call), `src/cli/daemon.ts`, `src/scripts/hauler.ts` (process
  entry), `src/skills`. Everything else lives under `src/internal/<owner>/`
  (`docs/architecture.md` is the ownership map); do not reintroduce a
  hand-written server, argv parser, or string-concatenated documents — add a
  component and a view-model.
- Documents must stay honest: a daemon the probe could not reach renders as
  `stopped`/`unresponsive` with its typed reason, never as an empty success.
- Daemon stop results carry their typed shutdown outcome. Only confirmed exit
  or confirmed prior absence is success; acknowledgement alone is not stopped.
- Names are `hauler` / `cargo-hauler` / `CARGO_HAULER_*`. No other prefix is
  read; never add an alias.

## Effect version

This branch is **Effect v4** (`effect` 4.0.0-rc.117), not v3. v3 idioms
(`Context.Tag`, `Data.TaggedError`, `@effect/platform` as a separate package)
often do not apply; check the vendored v4 source before assuming an API exists.

## Learning more about Effect

This branch is Effect v4. Prefer `node_modules/effect` (and
`node_modules/effect/AGENTS.md`) for APIs you are about to use; follow its
links when the guide points deeper. For APIs the guide does not cover, search
`node_modules/effect/src` and the vendored monorepo at `repos/effect` (same
pin; never import from it). Do not blanket-read the whole Effect tree before
unrelated edits.

## `repos/` — vendored reference source (read-only)

`repos/effect` is the Effect monorepo vendored as a git subtree, pinned to the
`effect@4.0.0-rc.117` tag — the exact version in `package.json`. It exists so
agents can read real source instead of guessing or searching the web.

Rules:

- **Never edit anything under `repos/`.** It is reference material, not part of
  this codebase. It is updated only by re-running `git subtree pull`.
- **Never import from `repos/` in application code.** Runtime dependencies come
  from `node_modules` via `package.json`. `repos/effect` is not a workspace
  package and is excluded from `tsconfig.json` includes, test globs, and the
  build.
- **Prefer the vendored source over web search.** Web results are dominated by
  Effect v3 and are frequently wrong for this branch. The tree in
  `repos/effect` is the ground truth for 4.0.0-rc.117.
- **Read `repos/effect/LLMS.md` first** when writing Effect code. It is the
  agent-facing guide to v4 idioms (`Effect.gen`, `Effect.fn`,
  `Context.Service`, `Schema.TaggedError`, Layers, testing) and links into
  runnable examples under `repos/effect/ai-docs/`.
- When writing Effect v4 code, inspect `repos/effect/packages/effect/src/` for
  idiomatic usage. `specs/reference/reference-repos.md` indexes the paths that
  matter for this project.
- Migrating v3-shaped code? See `repos/effect/MIGRATION.md`.