# Packer Learn

This directory contains didactic packer knowledge.

## Purpose

`learn/` exists to teach, not merely to store historical leftovers.

Use it to:

- explain packer architecture in a way new contributors can absorb quickly,
- consolidate conclusions from completed decisions and PRs,
- document common pitfalls and anti-patterns,
- connect normative specs to practical reasoning and implementation reality.

## What Belongs Here

A `learn` artifact should usually include:

1. the original problem,
2. the decision that resolved it,
3. the implemented or specified final model,
4. practical examples,
5. common mistakes and warnings,
6. links to the relevant specs and PRs.

Good `learn` material reduces onboarding time and prevents the same architectural confusion from repeating.

## Writing Rules

- Prefer didactic structure over chronological accumulation.
- Explain why the model exists, not only what it is.
- Keep terminology aligned with packer specs.
- Refactor older material when the directory starts feeling like a document graveyard.

## Refactor Rule

This directory should be periodically reorganized for better presentation.

If content grows, prefer:

- thematic grouping,
- overview documents,
- explicit learning paths,
- and consolidation of duplicated explanations.

The goal is a maintainable learning surface, not a passive archive.

## Current Learning Path

Start here:

1. [`mental-model-packer.md`](./mental-model-packer.md)
2. [`mental-model-asset-identity-and-runtime-contract.md`](./mental-model-asset-identity-and-runtime-contract.md)
3. [`mental-model-metadata-convergence-and-runtime-sink.md`](./mental-model-metadata-convergence-and-runtime-sink.md)
