# Portfolio Versioning

**Current portfolio version:** `V1`

**Current release state:** public V1 preview (`pre-publication` in machine
metadata), before the first stable release

`VERSION` is the single source of truth for the human-readable portfolio
version. The `portfolio.version` field in `books.json` mirrors that file for
publication tooling. All books, localized editions, and publish-ready short
forms inherit the portfolio version unless a future release record explicitly
places one project on an independent release track.

## What V1 Means

`V1` identifies the entire present body of work from initial construction
through the first stable publication gate. It is not a claim that every
manuscript is already stable, externally reviewed, or publicly released.

Do not create internal labels such as `V1.1`, `V1.2`, “second edition,” or
“next edition” to describe work completed before the first stable release.
Use a Git commit hash and, when useful, an ISO date to identify an exact
development snapshot:

```text
Portfolio version: V1
Manuscript commit: <full Git commit hash>
Checked on: YYYY-MM-DD
```

Descriptive cover phrases such as “field guide,” “catechism edition,” or
“household formation edition” identify a book's purpose or format. They are not
portfolio version numbers.

## First Stable Release

The portfolio remains `V1` until the requirements in
`docs/publication/v1-release-gate.md` have been completed and recorded. At that
point, the release owner should:

1. record the exact commit containing the approved sources;
2. record the disposition of all release-blocking review findings;
3. build and archive the approved deliverables from that commit;
4. create a deliberate stable Git tag, normally `v1.0.0`; and
5. update the release state in `books.json` and the release record without
   silently changing the reader-facing `V1` identity.

Later public revisions require a separately approved versioning decision. They
must not be inferred from internal drafts, historical research labels, or the
number of times a manuscript was rewritten.

## Exact-Snapshot Rules

- Use full Git commit hashes in durable review and source records.
- A date alone is not an exact source identifier.
- A branch name is not a release identifier.
- Never reinterpret historical construction labels as public releases.
- Keep localized editions tied to the same portfolio version while recording
  their own manuscript commit, reviewer findings, and release readiness.