AGENTS.md@packages/core git:20261009.95ca1efA

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

# @shadowclone/core

The base of every package. It holds the product identity, project paths, configuration, file and process helpers, and local storage.

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

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

- Package name: `@shadowclone/core`
- Workspace dependencies: none
- External dependencies: `smol-toml`, `zod`
- Export subpaths: `.`, `./testing`, `./product.json`

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

## Owns

- `src/config/`: source ids, `defaultConfig`, `applyManagedPolicy`, `readManagedPolicy`, and `EngineId`.
- `src/paths.ts`: `createProjectPaths`, `projectPaths`, and `canonicalPath`.
- `src/io/`: `runCommand`, `runProcess`, `runHostCommand`, `readBoundedFile`, `safeFilePath`, and the size limits.
- `src/storage/`: owner-only writes with `ownedDirectory`, `ownedFile`, and `ownedWrite`.
- `src/localFiles/`: `readLocalFile`, `replaceLocalText`, `acquireLocalLock`, and `fingerprint`.
- `src/distribution.ts`: finds `skills/` and `preferences/` in a checkout or an install.
- `src/product.json`: the product name and version.

## Rules

- This package has no workspace dependency. The boundary check enforces this.
- Every source in `defaultConfig` is `false`. A new source needs its own flag and an entry in `docs/data-handling.md`.
- `applyManagedPolicy` can only turn a setting off. A managed policy never widens the user config.
- Private state uses mode `0o700` for folders and `0o600` for files.
- `replaceLocalText` refuses a symbolic link. It fails when the file changed after the caller read it.

## Tests

Run `bun test` in this folder, or `bun test packages/core` from the root. The `./testing` export gives `integrationFixture` and `checkoutRoot`. The `hostCommand` tests run `git`.

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