Trim agent instructions

AGENTS.md

@@ -1,84 +1,55 @@
-# AGENTS.md
+# Executor policy
 
-Principles: the contracts that stay true while implementations churn. For how to
-run, boot, share, or navigate things today, see [RUNNING.md](RUNNING.md); for
-e2e scenarios, [e2e/AGENTS.md](e2e/AGENTS.md). Run `bun run bootstrap` first in
-any fresh checkout or worktree.
+Stable contracts live here. Current setup and server mechanics are in
+[RUNNING.md](RUNNING.md); e2e invariants are in
+[e2e/AGENTS.md](e2e/AGENTS.md). Run `bun run bootstrap` in every fresh rift.
 
-## Task Completion
+## Verification and evidence
 
-- Tests use Effect Vitest. Run scoped tests with `vitest run ...`. `bun run test`
-  is fine (it delegates to Vitest); NEVER run `bun test`.
-- Run the narrowest useful verification for a change. For broad or merge-ready
-  work the full gates are `bun run format:check`, `lint`, `typecheck`, `test`.
-- Run `bun run format` before opening a PR, staging only files your branch
-  touched (leave unrelated files `format` rewrites out of the PR).
+- Tests use Effect Vitest. Run scoped tests with `vitest run ...` or the
+  package script. Never use `bun test`.
+- Use the narrowest meaningful verification while iterating. Merge-ready gates
+  are `bun run format:check`, `lint`, `typecheck`, and `test`.
+- Run `bun run format` before a PR and include only files owned by the branch.
+- User-visible work requires a specific e2e run, a browsable dev instance, and
+  the recording or trace showing what to inspect. Add a scenario when none
+  covers the changed behavior.
 
-## Handing Back Work: Evidence, Not Assertions
+## Service emulators
 
-"Done" is something the user can open, not a claim. When work changes what a user
-sees, hand back: an e2e run that proves it (link the specific run with one line
-on what to look at, not a wall of green), the dev server left running so they can
-poke at it, and the paths worth trying by hand including ones no scenario covers
-yet. If no scenario covers the change, write one, and embed its recording in the
-PR. The machinery runs in reverse too: seed an environment into a state
-(reproduce a bug live, stage data) and hand across the link.
+Tests and demos that need an upstream API, OAuth/OIDC provider, or webhook use
+the published `@executor-js/emulate` emulators rather than stubs. They provide
+wire-level state, real-shaped credentials, OpenAPI descriptions, and request
+ledgers. Create per-run hosted instances through the service's
+`/_emulate/instances` control route.
 
-## Service Emulators
+Emulate is a separate project. Make emulator changes there and consume the
+published package here; never re-vendor or create a parallel fake inside
+executor.
 
-For any test or demo needing an upstream API, OAuth/OIDC provider, or webhook
-source, use the `@executor-js/emulate` emulators instead of writing a stub:
-wire-level and stateful, real SDKs run unmodified, each serves a full OpenAPI
-spec, mints real-shaped credentials, and records every call in a request ledger
-to assert against. Hosted on emulators.dev (create a per-run instance via
-`POST https://<service>.emulators.dev/_emulate/instances`). See the `emulate`
-skill (`.claude/skills/emulate/SKILL.md`). They are a standalone project
-(`github.com/UsefulSoftwareCo/emulate`) consumed here as the published package:
-full autonomy to change, publish, and deploy them on their `main`; don't re-vendor.
-
-## Attribution
-
-No AI/Claude/Anthropic/Co-Authored-By attribution in commits, messages, PRs, or
-generated files. PR titles and descriptions go to a public repo: no internal info
-or specific names unless explicitly stated.
-
-## Collaboration Notes
-
-- The user uses speech-to-text; infer likely intent from odd wording, ask only
-  when needed.
-- Code is cheap to write: no time estimates, implementation time isn't a blocker.
-- Never use em-dashes anywhere. Use commas, colons, parentheses, or separate
-  sentences.
-
-## Reference Repos
-
-Repos in `.reference` (Effect, effect-atom, …) are available for patterns. Clone
-a given Git URL into `.reference` and pull latest before using it.
-
-## Engineering Priorities
+## Engineering boundaries
 
 - Prefer correctness and predictable behavior over short-term convenience.
-- Preserve runtime behavior when changing lint, typing, or test structure.
-- Keep package boundaries clear; use public package exports, not cross-package
-  relative imports.
-- Extract shared logic only when the shared behavior is real; avoid broad generic
+- Preserve runtime behavior during lint, typing, and test-structure changes.
+- Use public package exports; never cross package boundaries with relative
+  imports.
+- Extract shared logic only for genuinely shared behavior. Avoid generic
   abstractions for one-off duplication.
+- Public PRs, commits, generated files, and documentation contain no private
+  names, internal context, customer-derived data, or AI attribution.
 
-## Package Roles
+## Package ownership
 
-- `packages/core/sdk`: core contracts, plugin wiring, scopes, integrations, secrets,
-  policies, fixtures. `@executor-js/sdk/http-auth` carries the shared auth-method
-  vocabulary the HTTP protocol plugins compose (core never imports it, keeping it
-  carrier-agnostic).
+- `packages/core/sdk`: contracts, plugin wiring, scopes, integrations, secrets,
+  policies, and fixtures. Shared HTTP auth vocabulary lives in
+  `@executor-js/sdk/http-auth`; core remains carrier-agnostic.
 - `packages/core/storage-*`: storage adapters and test support.
-- `packages/plugins/*`: protocol and provider plugins; their runtime, React, API,
-  and testing helpers live with the owning plugin.
-- `packages/react`: shared React UI and atom/client integration.
+- `packages/plugins/*`: protocol/provider implementations and their runtime,
+  React, API, and testing helpers.
+- `packages/react`: shared React UI and client/atom integration.
 - `packages/hosts/mcp`: MCP host surface.
-- `packages/kernel/*`: execution runtimes and code execution substrate.
-- `apps/{local,cloud,cli,desktop}`: product entry points composing the packages.
-
-## Other
+- `packages/kernel/*`: execution runtimes and code-execution substrate.
+- `apps/{local,cloud,cli,desktop}`: product composition roots.
 
-Note mistakes in MISTAKES.md, missing context or tools in DESIRES.md, and env
-learnings in LEARNINGS.md.
+Record mistakes in `MISTAKES.md`, missing capabilities in `DESIRES.md`, and
+environment discoveries in `LEARNINGS.md`.