-`internal/notify`: notification interface and current no-op notifier.
-`internal/testutil`: shared test fixtures. Production code must not import this package.
-`docs`: current user, operator, policy, internal, and roadmap documentation.
-`examples`: copyable example configs and source bundles.
Do not create new top-level package families such as `pkg`, `internal/stage`,
`internal/modules`, or service-specific adapter directories unless the
architecture policy or a current roadmap explicitly calls for them.
## Common Commands
Run the full test suite:
```bash
go test ./...
```
Run targeted packages while developing:
```bash
go test ./internal/config
go test ./internal/cli ./internal/app
go test ./internal/publish ./internal/state
go test ./internal/transform/markdown
```
Run the CLI against an example config:
```bash
go run ./cmd/distributor run --config examples/local-publish.yml --dry-run
```
Validate or inspect a local source bundle:
```bash
go run ./cmd/distributor validate examples/source-bundle
go run ./cmd/distributor inspect examples/source-bundle
```
If Go cache permissions fail in a restricted environment, use workspace-safe
temporary caches:
```bash
GOCACHE=/private/tmp/distributor-gocache GOMODCACHE=/private/tmp/distributor-gomodcache go test ./...
```
## Coding Conventions
- Keep the application small, explicit, and dependency-light.
- Prefer package-local helpers over broad abstractions until behavior is shared by multiple packages.
- Keep CLI parsing in `internal/cli`; business decisions belong in `internal/app`, `internal/bundle`, `internal/publish`, `internal/state`, and related core packages.
- Keep adapter packages thin. Backend-specific filesystem or service behavior belongs in adapters; bundle, state, transform, and publish policy belongs outside adapters.
- Preserve public CLI behavior, config semantics, manifest schema, destination state schema, and local MVP behavior unless the current task explicitly changes them.
- Use `storage.DisplayPath`, `storage.StateFileName`, `storage.StatePath`, and `storage.ManagedBundleTargets` instead of duplicating those conventions.
- Use `bundle.ValidateManifest` for normalized source manifest semantics, including embedded source manifests in destination state.
- Use `config.ValidatePublishTransformPolicy` for publish and transform policy combinations.
- Do not import concrete transform implementations from `internal/publish`; app-level wiring owns transform registration.
- Do not import `internal/testutil` from production code.
## Dependency Policy
The project currently depends on:
-`gopkg.in/yaml.v3` for YAML configuration loading.
-`github.com/yuin/goldmark` for Markdown rendering.
Add external dependencies only when they materially improve correctness,
security, interoperability, or implementation complexity. Avoid dependencies
for small conveniences. Do not let dependency-specific types leak across
internal package boundaries unless that dependency is the explicit package
contract.
## Configuration Changes
When adding or changing configuration:
1. Update `internal/config/config.go` structs and YAML tags.
2. Add defaults in `internal/config/defaults.go` only for built-in defaults.
3. Add validation in `internal/config/validate.go` with clear field context.
4. Update config load and validation tests.
5. Update `docs/config.md` in the same change if current user-visible config behavior changes.
6. Update examples only with configs that are valid and executable for implemented behavior.
Config validation may accept fields for backends that are not executable yet,
but user-facing docs and examples must clearly state execution support. At the
