Save this content to: .claude/skills/lean-dist/SKILL.md

# Lean dist

## When to apply

- Adding a new top-level directory (tests/, docs/, .ai/, etc.)
- Reviewing a PR that touches .gitattributes
- Package's dist size feels too large

## The contract

Every path NOT needed at runtime should be `export-ignore`d so Composer's
dist installer skips it. Two layers produce that — and neither is a list
to hand-maintain in this skill:

- **The managed block** — `vendor/bin/package-boost-php gitattributes`
  writes package-boost-php's canonical AI/agent entries into the
  `# >>> package-boost (managed) >>>` block: the per-agent directories
  (`.ai/`, `.claude/`, `.cursor/`, …) and the root agent files
  (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, plus the `.cursorrules` /
  `.windsurfrules` dotfiles). The exact set is generated by the command —
  read the live block, not a copy in this skill.
- **The full lean set** — `.lpv` is the single source of truth for the
  complete export-ignore set the validator checks: the managed AI/agent
  entries above plus dev tooling, tests, and lock files (`tests/`,
  `composer.lock`, `phpstan.neon.dist`, `pint.json`, …). Edit `.lpv`, not
  a list here.

## Verifying

Run `vendor/bin/package-boost-php lean` (this package) or directly via
`vendor/bin/lean-package-validator validate`. Both check the
`.gitattributes` against `.lpv` rules.

Add to CI:

```yaml
- name: Validate lean dist
  run: vendor/bin/package-boost-php lean
```

## Validation is opt-in; the managed block is the baseline

Two distinct tools, two roles — don't conflate them:

- `vendor/bin/package-boost-php gitattributes` writes and refreshes the
  managed block. This is what actually makes the archive lean; you run
  it during setup and whenever a new top-level path needs excluding.
  Baseline, not optional.
- `vendor/bin/package-boost-php lean` (the `stolt/lean-package-validator`
  wrapper) only *checks* that the block stays complete. It is opt-in:
  wire it into CI if you want enforcement, but a package whose managed
  block is correct ships lean whether or not the validator ever runs.
  There is no default `.lpv` / composer-script wiring — add it only if
  you want the stricter gate.

If your `.gitattributes` export-ignore is already covered by the managed
block (e.g. confirmed by a repo-init audit), the validator is
redundant-but-harmless, not a missing requirement.

## Anti-patterns

- Editing `.gitattributes` outside the managed block to add boost-managed
  entries — package-boost will rewrite the block on next sync
- Forgetting `export-ignore` on a new top-level dir → users get bloat
- Mixing `export-ignore` with diff/merge attributes on the same line
  (works, but visually noisy; separate the concerns)

## See also

- `.lpv` file in this package's root for the canonical exclusion list
- `references/gitattributes-managed-block.md` in
  `sandermuller/repo-init` for the multi-tool managed-block contract