AGENTS.md@packages/environment git:20261009.95ca1efA

Immutable. This exact content never changes and is served at /api/v1/blob/949a32593e817260.

# @shadowclone/environment

Holds what agents receive: the environment record, skill publication, native instruction sections, hooks, install, and undo.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/environment`
- Workspace dependencies: `@shadowclone/agents`, `@shadowclone/changes`, `@shadowclone/core`, `@shadowclone/profile`, `@shadowclone/redact`, `@shadowclone/sessions`, `@shadowclone/skills`
- External dependencies: `zod`
- Export subpaths: `.`, `./testing`, `./browser`

<!-- package-facts:end -->

## Owns

- `src/environment/`: the store (`readEnvironment`, `writeEnvironment`), `publishEnvironmentRevision`, `undoRevision`, `syncLearningEnvironment`, and `environmentStatus`.
- `src/environment/builds/` and `harness/`: build definitions, routing text, and the harness manifest.
- `src/integrations/`: native sections, hooks, `installIntegration`, `uninstallIntegration`, and `compileContext`.
- `src/integrations/installation/`: the install record and artifact ownership checks.

## Rules

- Every write goes through `publishEnvironmentRevision`. A path outside the authorized destinations is an error.
- `undoRevision` takes the write lock. It refuses an unauthorized root and a revision that conflicts with later edits.
- Native routing text is at most 4096 bytes. A longer text is an error, and the old section stays.
- Shadowclone rewrites only the text between the `<shadowclone-guidance>` markers. Malformed markers are an error.
- Shadowclone replaces an installed file only when its fingerprint matches the install record. A manual edit stays.
- Migration copies the original skills and native instructions to `environment-baselines/` before it publishes.

## Tests

Run `bun test` in this folder, or `bun test packages/environment` from the root. The `./testing` export gives `learningRecord` and `skillFixture`. Several tests run `git` on temporary repositories.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.