# Packer Documentation

This directory contains the working, planning, and normative documentation for the `packer` domain.

`packer` is a standalone domain. It follows the same documentary cycle used elsewhere in the repository:

`agendas -> decisions -> pull-requests -> specs -> learn`

## Tree

```text
docs/packer/
├── agendas/
├── decisions/
├── learn/
├── pull-requests/
├── specs/
├── Prometeu Packer.md
└── README.md
```

## Responsibilities

### `Prometeu Packer.md`

`Prometeu Packer.md` is the current bootstrap specification for the domain.

Use it to:

- understand the current packer scope,
- recover the initial architecture and terminology,
- seed the split into smaller normative specs under `specs/`.

This document is useful as a draft source, but it should not become a permanent dumping ground for every future change.

### `agendas/`

`agendas/` contains open packer topics.

Use it to:

- frame unresolved problems,
- compare options and tradeoffs,
- define scope and non-goals,
- drive discussions toward a decision.

An agenda is a discussion artifact, not a final contract.

### `decisions/`

`decisions/` contains closed packer decision records.

Use it to:

- record the chosen direction,
- capture constraints and invariants,
- state what remains intentionally out of scope,
- identify which specs, plans, or code paths must be updated.

Decisions close debate. They are not brainstorming notes.

### `pull-requests/`

`pull-requests/` contains self-contained execution proposals.

Use it to:

- package a change for review,
- plan propagation across specs and implementation,
- define acceptance criteria,
- make tests and risks explicit before editing code or final specs.

### `specs/`

`specs/` contains the normative packer corpus.

Use it to:

- consolidate the official packer contract,
- split large draft material into stable chaptered specs,
- define behavior, constraints, interfaces, and conformance expectations.

Specs should only absorb already-closed decisions.

### `learn/`

`learn/` contains didactic consolidation.

Use it to:

- explain why the packer works the way it does,
- preserve hard-won operational knowledge,
- teach future contributors the model, pitfalls, and expected workflows,
- reorganize accumulated knowledge into a cleaner learning surface.

`learn/` is not an archive of old decisions.

## Recommended Flow

The preferred packer documentation flow is:

1. `agendas/`: open and shape the unresolved topic.
2. `decisions/`: close the architectural choice.
3. `pull-requests/`: plan how the decision will be propagated.
4. `specs/`: integrate the decision into normative text.
5. `learn/`: consolidate the final knowledge in a didactic form.

## Practical Rule

- `agendas/` stores open questions.
- `decisions/` stores closed answers.
- `pull-requests/` stores execution plans.
- `specs/` stores the normative packer contract.
- `learn/` stores teaching-oriented consolidation.

If implementation exposes a missing architectural choice, stop and return to `agendas/` or `decisions/`.