opkg 0.6.1 → 0.7.0

package/specs/install/package-yml-canonical.md

@@ -1,24 +1,24 @@
-### `package.yml` as Canonical for Install
+### `openpackage.yml` as Canonical for Install
 
-This document defines how `.openpackage/package.yml` interacts with the `install` command, and what it means for `package.yml` to be the **canonical** declaration of dependency intent.
+This document defines how `openpackage.yml` interacts with the `install` command, and what it means for `openpackage.yml` to be the **canonical** declaration of dependency intent.
 
-The aim is to make behavior predictable and avoid “CLI overrides” that silently diverge from `package.yml`.
+The aim is to make behavior predictable and avoid “CLI overrides” that silently diverge from `openpackage.yml`.
 
 ---
 
 ## 1. Canonical responsibility
 
 - **Canonical source of truth**:
-  - For the **current workspace**, `.openpackage/package.yml` is the **only authoritative declaration** of:
+  - For the **current workspace**, `openpackage.yml` is the **only authoritative declaration** of:
     - Which **direct dependencies** exist.
-    - Which **version ranges** apply to those dependencies.
+    - Which **source** and **version intent** apply to those dependencies.
   - This applies to both:
     - `packages` (regular dependencies).
     - `dev-packages` (development dependencies).
 
 - **Install’s role**:
   - `install` **never changes intent by itself**:
-    - It does **not mutate existing ranges** in `package.yml` unless explicitly asked by a future higher-level command (e.g. an `upgrade`).
+    - It does **not mutate existing ranges** in `openpackage.yml` unless explicitly asked by a future higher-level command (e.g. an `upgrade`).
     - It **materializes or refreshes** dependencies so the workspace matches the declared intent.
 
 ---
@@ -26,29 +26,44 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
 ## 2. Direct vs transitive dependencies
 
 - **Direct dependencies**:
-  - Declared in the workspace `.openpackage/package.yml`.
+  - Declared in the workspace `openpackage.yml`.
   - Fully controlled by the user.
-  - Canonical range comes from `package.yml`.
+  - Canonical range comes from `openpackage.yml`.
 
 - **Transitive dependencies**:
-  - Declared in other packages’ `package.yml` files (inside registry packages).
-  - Resolved entirely by the dependency resolver according to version constraints; they do not appear in the root `package.yml`.
+  - Declared in other packages’ `openpackage.yml` files (inside registry packages).
+  - Resolved entirely by the dependency resolver according to version constraints; they do not appear in the root `openpackage.yml`.
   - `install` may upgrade them within the declared ranges, but they are **not canonical at the root level**.
 
 ---
 
 ## 3. Mapping CLI input to canonical ranges
 
-### 3.1 Fresh packages (not yet in `package.yml`)
+### 3.0 Dependency entry schema (source fields)
+
+Each dependency entry MUST specify **exactly one** source field:
+
+- `version`: a registry range or exact version (`^1.2.0`, `1.2.3`, `*`, etc.)
+- `path`: a filesystem path to a package directory or tarball
+- `git`: a git URL (https/ssh/etc.) with optional `ref`
+
+Additional rules:
+
+- `ref` is only valid when `git` is present.
+- A dependency entry MUST NOT specify multiple sources (e.g. `version` + `path`).
+
+This keeps dependency intent unambiguous and aligns with modern package managers that treat source types as mutually exclusive.
+
+### 3.1 Fresh packages (not yet in `openpackage.yml`)
 
 - **Case A – `opkg install <name>`**:
   - No explicit range is provided.
   - The CLI:
     - Resolves **latest suitable version** from local+remote (see `version-resolution.md`).
-    - Adds `<name>` to `package.yml` with a **default range derived from that version**, e.g.:
+    - Adds `<name>` to `openpackage.yml` with a **default range derived from that version**, e.g.:
       - `^S` where `S` is the selected stable version.
-      - If only WIP/pre-release exists, the policy may:
-        - Use an **exact WIP version** in `package.yml`, or
+      - If only a pre-release exists, the policy may:
+        - Use an **exact pre-release version** in `openpackage.yml`, or
         - Use a range that explicitly includes that pre-release.
       - If the selected version is **unversioned** (manifest omits `version`, represented as `0.0.0` internally), persist the dependency entry **without a `version` field** (bare name), rather than writing `0.0.0`.
 
@@ -58,11 +73,11 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
     - Uses `<spec>` as the range for selecting a concrete version.
     - On success:
       - Installs the selected version.
-      - **Persists `<spec>` as-is** in `package.yml` (except for any normalization strictly required by the version-range parser).
+      - **Persists `<spec>` as-is** in `openpackage.yml` (except for any normalization strictly required by the version-range parser).
 
-### 3.2 Existing packages (already in `package.yml`)
+### 3.2 Existing packages (already in `openpackage.yml`)
 
-- Let **`R_pkg`** be the range string stored in `package.yml` for `<name>`.
+- Let **`R_pkg`** be the range string stored in `openpackage.yml` for `<name>`.
 
 - **Case C – `opkg install <name>`**:
   - The canonical range is **`R_pkg`**.
@@ -83,15 +98,28 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
     - Outcomes:
       - If `<spec>` is **compatible** with `R_pkg`:
         - Proceed using **`R_pkg` as the effective range** for resolution.
-        - Optionally log a message: “Using version range from package.yml (`R_pkg`); CLI spec `<spec>` is compatible.”
+        - Optionally log a message: “Using version range from openpackage.yml (`R_pkg`); CLI spec `<spec>` is compatible.”
       - If `<spec>` is **incompatible** with `R_pkg`:
         - **Fail with a clear error**, for example:
-          - “Version spec `<spec>` conflicts with `package.yml` range `R_pkg` for `<name>`. Edit `.openpackage/package.yml` if you intend to change the dependency line.”
+          - “Version spec `<spec>` conflicts with `openpackage.yml` range `R_pkg` for `<name>`. Edit `openpackage.yml` if you intend to change the dependency line.”
         - No installs or upgrades are performed.
 
+### 3.3 Path and git dependencies (non-registry sources)
+
+When a dependency uses `path` or `git`, it is treated as a **source-pinned** dependency rather than a semver-ranged registry dependency:
+
+- The installed content is loaded from that source.
+- The installed package version comes from the dependency’s own `openpackage.yml`.
+- `install` MUST NOT write a registry `version` range for `path`/`git` dependencies.
+
+For git dependencies:
+
+- `git` stores the repository URL.
+- `ref` optionally stores the branch/tag/commit provided by the user.
+
 ---
 
-## 4. When and how `package.yml` is mutated
+## 4. When and how `openpackage.yml` is mutated
 
 ### 4.1 Allowed mutations by `install`
 
@@ -103,8 +131,12 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
     - Remove existing entries.
     - Rewrite existing version ranges.
 
+- **Adding source-pinned dependencies**:
+  - When installing from `path` or `git`, `install` persists the dependency using the corresponding source fields.
+  - It must not add a `version` field in these cases (source-pinned dependencies are not semver-ranged).
+
 - **Rewriting malformed entries (edge case)**:
-  - If `package.yml` contains a **syntactically invalid** version range for a dependency that the user is trying to install:
+  - If `openpackage.yml` contains a **syntactically invalid** version range for a dependency that the user is trying to install:
     - The primary expectation is to **fail with a clear error** and ask the user to fix the YAML.
     - Auto-rewriting malformed entries should **not** happen silently.
 
@@ -114,13 +146,13 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
   - `save` / `pack` and any future `upgrade`-like commands are responsible for:
     - Intentionally changing version lines.
     - Bumping base versions for stable lines.
-  - Therefore, `install` **never auto-bumps** the declared ranges in `package.yml`.
+  - Therefore, `install` **never auto-bumps** the declared ranges in `openpackage.yml`.
 
 - **Auto-tracking of workspace-owned packages (`save` / `pack`)**:
   - When a package developed in the current workspace is first added as a dependency:
     - `save` / `pack` persist a **default caret range** derived from the new stable, e.g. `^1.2.3`.
   - On subsequent `save` / `pack` operations for that same package:
-    - Let `R_pkg` be the existing range in `package.yml` and `S_new` the new stable base version (e.g. `2.0.0`).
+    - Let `R_pkg` be the existing range in `openpackage.yml` and `S_new` the new stable base version (e.g. `2.0.0`).
     - **Special case: Prerelease-to-stable transition during `pack`**:
       - If `R_pkg` includes explicit prerelease intent (e.g. `^1.0.0-0`) and `S_new` is a stable version on the same base line (e.g. `1.0.0`):
         - Then `pack` **updates** `R_pkg` to a stable range (e.g. `^1.0.0`) to reflect the transition from prerelease to stable.
@@ -129,7 +161,7 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
     - If `S_new` **already satisfies** `R_pkg` (e.g. `R_pkg = ^1.0.0`, `S_new = 1.0.1`):
       - **The constraint is left unchanged**; `save` / `pack` do not rewrite `R_pkg`.
     - If `S_new` is **outside** `R_pkg` (e.g. `R_pkg = ^1.0.0`, `S_new = 2.0.0`):
-      - `save` / `pack` may **auto-update** the dependency line in `package.yml` to a new caret range `^S_new` to keep the workspace tracking the new stable line.
+      - `save` / `pack` may **auto-update** the dependency line in `openpackage.yml` to a new caret range `^S_new` to keep the workspace tracking the new stable line.
   - This auto-tracking behavior:
     - Applies only to dependencies managed via `save` / `pack` for workspace-owned packages.
     - Never changes constraints that already include the new stable version (except for the prerelease-to-stable transition exception above).
@@ -138,22 +170,22 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
 
 ## 5. Conflict scenarios & UX
 
-### 5.1 CLI vs `package.yml` disagreement
+### 5.1 CLI vs `openpackage.yml` disagreement
 
 - **Scenario**:
-  - `package.yml`: `foo: ^1.2.0`
+  - `openpackage.yml`: `foo: ^1.2.0`
   - User runs: `opkg install foo@2.0.0`
 
 - **Behavior**:
   - Detect that `<spec> = 2.0.0` is **outside** `^1.2.0`.
   - Fail with a message similar to:
-    - “Requested `foo@2.0.0`, but `.openpackage/package.yml` declares `foo` with range `^1.2.0`. Edit `package.yml` to change the dependency line, then re-run `opkg install`.”
+    - “Requested `foo@2.0.0`, but `openpackage.yml` declares `foo` with range `^1.2.0`. Edit `openpackage.yml` to change the dependency line, then re-run `opkg install`.”
 
-### 5.2 Existing install but changed `package.yml`
+### 5.2 Existing install but changed `openpackage.yml`
 
 - **Scenario**:
   - Previously: `foo` declared as `^1.2.0`, installed `1.3.0`.
-  - User edits `package.yml` to `foo: ^2.0.0`.
+  - User edits `openpackage.yml` to `foo: ^2.0.0`.
   - Then runs `opkg install` or `opkg install foo`.
 
 - **Behavior**:
@@ -162,10 +194,10 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
   - Install or upgrade to that version, even if it requires pulling from remote.
   - Optionally log a message noting that the base line changed, similar to the save/pack reset messages (but this is informational only).
 
-### 5.3 Dependency removed from `package.yml`
+### 5.3 Dependency removed from `openpackage.yml`
 
 - **Scenario**:
-  - `foo` used to be in `package.yml`.
+  - `foo` used to be in `openpackage.yml`.
   - User removes `foo` from both `packages` and `dev-packages`.
   - `foo` may still be installed under `.openpackage` from a previous state.
 
@@ -187,7 +219,7 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
   - Re-installs with an existing `files` list **reuse** that list as canonical; a TTY prompt may offer to clear it to switch back to a full install.
   - Supplying a new path via CLI for a dependency that already has `files` **adds** the path (deduped) before install.
   - Removing the `files` field (or setting it to `null`/empty) returns the dependency to **full-install semantics**.
-  - If a dependency is currently full (no `files`), a path-based install attempt is **rejected**; convert to partial by editing `package.yml` or reinstalling after removal.
+  - If a dependency is currently full (no `files`), a path-based install attempt is **rejected**; convert to partial by editing `openpackage.yml` or reinstalling after removal.
 
 - **Matching rules**:
   - Paths in `files` are **exact registry paths** (no globs) and are normalized when persisted.
@@ -198,7 +230,7 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
 ## 7. Summary invariants
 
 - **I1 – Canonical intent**:
-  - For direct dependencies, **`package.yml` is always the source of truth**.
+  - For direct dependencies, **`openpackage.yml` is always the source of truth**.
   - CLI specs cannot silently override it; at most they can:
     - Seed new entries (fresh installs).
     - Act as compatibility hints for existing entries.
@@ -209,8 +241,8 @@ The aim is to make behavior predictable and avoid “CLI overrides” that silen
     - Only **adds new entries** when installing fresh dependencies.
 
 - **I3 – Explicit edits for semantic changes**:
-  - To change which major version line a dependency tracks, the user **edits `package.yml`**, not `install` flags.
+  - To change which major version line a dependency tracks, the user **edits `openpackage.yml`**, not `install` flags.
   - This mirrors the mental model from the save/pack specs:
-    - “`package.yml` version is what I’m working toward; commands operate relative to that declaration.”
+    - “`openpackage.yml` version is what I’m working toward; commands operate relative to that declaration.”
 
 

package/specs/install/version-resolution.md

@@ -3,10 +3,10 @@
 This document specifies how `install` chooses **which concrete version** of a package to install, given:
 
 - A **package name**.
-- An **effective version constraint** (from `package.yml` and/or CLI).
+- An **effective version constraint** (from `openpackage.yml` and/or CLI).
 - Access to **local registry versions** and optionally **remote registry metadata**.
 
-The goal is to implement **“latest in range from local+remote”** deterministically, with clear WIP vs stable semantics.
+The goal is to implement **“latest in range from local+remote”** deterministically, with clear pre-release vs stable semantics.
 
 ---
 
@@ -16,11 +16,11 @@ The goal is to implement **“latest in range from local+remote”** determinist
 - **Constraint**:
   - A string understood by `version-ranges` (exact, caret, tilde, wildcard, comparison).
   - Examples: `1.2.3`, `^1.2.0`, `~2.0.1`, `>=3.0.0 <4.0.0`, `*`, `latest`.
-- When a dependency entry in `package.yml` omits `version`, the effective constraint is treated as `*` (wildcard).
+- When a dependency entry in `openpackage.yml` omits `version`, the effective constraint is treated as `*` (wildcard).
 - **Local versions**:
   - Semver versions discoverable via `listPackageVersions(name)` from the **local registry**.
-  - May include a `0.0.0` entry when the package has no `version` in `package.yml`.
-  - Includes both **stable** and **WIP/pre-release** semver versions, e.g. `1.2.3`, `1.2.3-000fz8.a3k`.
+  - May include a `0.0.0` entry when the package has no `version` in `openpackage.yml`.
+  - Includes both **stable** and **pre-release** semver versions, e.g. `1.2.3`, `1.2.3-beta.1`.
 - **Remote versions**:
   - Semver versions discoverable via remote metadata APIs (e.g. via `fetchRemotePackageMetadata` / registry metadata).
   - May include a `0.0.0` entry when the remote package has no versioned releases yet.
@@ -33,12 +33,12 @@ The goal is to implement **“latest in range from local+remote”** determinist
 - **Base rule**:
   - The **effective `available` set** depends on the resolution mode and scenario, and this rule is applied **uniformly** to:
     - The **root package** being installed.
-    - **All recursive dependencies** discovered from `package.yml` files.
+    - **All recursive dependencies** discovered from `openpackage.yml` files.
     - Any **pre-flight checks or validations** that need to answer “what version would be chosen?” for a given name + constraint.
     - **Local-only / explicit `--local`**:
       - **`available = local`**.
       - Remote metadata is **never** consulted; if no satisfying local version exists, resolution fails (see error behavior).
-    - **Fresh dependency installs in default mode** (e.g. `opkg install <name>` or `opkg install <name>@<spec>` where `<name>` is **not yet declared** in `package.yml`):
+    - **Fresh dependency installs in default mode** (e.g. `opkg install <name>` or `opkg install <name>@<spec>` where `<name>` is **not yet declared** in `openpackage.yml`):
       - Version selection is **local-first with remote fallback**, regardless of whether the effective constraint is a wildcard or an explicit range:
         - Step 1 – **Local-only attempt**:
           - Start with **`available_local = local`**.
@@ -53,7 +53,7 @@ The goal is to implement **“latest in range from local+remote”** determinist
               - Resolution fails with a clear error that:
                 - Explains that no satisfying local version exists, and
                 - Mentions that remote lookup also failed (or was disabled).
-    - **Existing dependencies in default mode** (e.g. entries already in `package.yml`, or dependencies declared in nested `package.yml` files during recursive resolution):
+    - **Existing dependencies in default mode** (e.g. entries already in `openpackage.yml`, or dependencies declared in nested `openpackage.yml` files during recursive resolution):
       - Resolution also follows a **local-first with remote fallback** policy:
         - Step 1 – **Local-only attempt**:
           - Use **only local registry versions** that match the declared range to build `available_local`.
@@ -89,7 +89,7 @@ The goal is to implement **“latest in range from local+remote”** determinist
 - **Invalid constraints**:
   - If the constraint string cannot be parsed:
     - The install operation **fails early** with a clear error.
-    - The user is instructed to fix the version in `package.yml` for canonical cases, or in the CLI for fresh installs.
+    - The user is instructed to fix the version in `openpackage.yml` for canonical cases, or in the CLI for fresh installs.
 
 ---
 
@@ -102,142 +102,98 @@ Given `available: string[]` and a parsed constraint:
   - Otherwise:
     - Fail with **"version not found"** and list the nearest available versions (see error UX section).
 
-- **If constraint is `wildcard` / `latest`** (default behavior):
+- **If constraint is `wildcard` / `latest`**:
   - Use `semver.maxSatisfying(available, '*', { includePrerelease: true })` to find the **highest semver version**.
-  - **Select the single highest semver version**, stable or WIP/pre-release (if only `0.0.0` exists, it is selected).
-  - If the selected version is a pre-release/WIP, the CLI should make that explicit in its output.
+  - **Select the single highest semver version**, stable or pre-release (if only `0.0.0` exists, it is selected).
+  - If the selected version is a pre-release, the CLI should make that explicit in its output.
 
-- **If constraint is `caret`, `tilde`, or `comparison`** (default behavior):
+- **If constraint is `caret`, `tilde`, or `comparison`**:
   - Use `semver.maxSatisfying(available, range, { includePrerelease: true })` to find the **highest satisfying version**.
-  - **Select that version** (stable or pre-release/WIP). `0.0.0` satisfies ranges according to standard semver rules.
-  - No additional "downgrade WIP to stable" heuristic is applied; WIP/pre-release versions are first-class semver versions for resolution purposes.
-
-- **With `--stable` flag**:
-  - The selection follows the **stable-preferred policy** described in §5.2.
-  - For wildcard/ranges: if any satisfying stable version exists, pick the **latest satisfying stable**.
-  - Only pick prerelease/WIP when **no satisfying stable exists at all**.
+  - **Select that version** (stable or pre-release). `0.0.0` satisfies ranges according to standard semver rules.
+  - No additional "downgrade pre-release to stable" heuristic is applied; pre-release versions are first-class semver versions for resolution purposes.
 
 If no version satisfies the constraint:
 
 - The operation **fails** with:
   - A clear description of:
     - The requested range.
-    - The set of available stable and WIP versions.
+    - The set of available stable and pre-release versions.
   - Suggestions for:
-    - Editing `package.yml` to broaden the range.
-    - Using `pack` / `save` to create a compatible version.
+    - Editing `openpackage.yml` to broaden the range.
+    - Using `pack` (or pulling from remote) to create a compatible version.
 
 ---
 
-## 5. WIP vs stable selection policy
+## 5. Pre-release vs stable selection policy
 
 ### 5.1 Definitions
 
 - Let **`S`** be a stable version string, e.g. `1.2.3`.
-- Let **`W(S)`** be the set of WIP versions derived from `S`, e.g.:
-  - `1.2.3-<t>.<w>`.
+- Let **`P(S)`** be the set of pre-release versions derived from `S`, e.g.:
+  - `1.2.3-beta.1`.
 
-### 5.2 Default policy: Latest wins (stable and WIP treated uniformly)
+### 5.2 Latest wins policy (stable and pre-release treated uniformly)
 
 - **Latest-in-range selection**:
   - Among all versions that satisfy the constraint, **choose the highest semver version** according to normal semver ordering (with pre-releases ordered per semver).
-  - WIP versions (`S-<t>.<w>`) are just a subset of pre-release versions; there is no special demotion to their base stable.
-  - This ensures that `opkg install <name>` naturally selects the newest available version, including WIPs, which is useful for development workflows.
+  - Pre-release versions are first-class semver versions; there is no special demotion to their base stable.
+  - This ensures that `opkg install <name>` naturally selects the newest available version, including pre-releases, which can be useful for development workflows.
 
 - **Pre-release transparency**:
-  - When the chosen version is a pre-release/WIP, the CLI **surfaces that fact** in messages and summaries, but does not alter the chosen version.
+  - When the chosen version is a pre-release, the CLI **surfaces that fact** in messages and summaries, but does not alter the chosen version.
   - This helps users understand when they're working with pre-release code.
 
-### 5.3 Stable-preferred policy (used with `--stable` flag)
-
-- **Stable dominates WIP for the same base line**:
-  - If both:
-    - A stable `S`, and
-    - One or more WIPs in `W(S)`
-    **satisfy the constraint**, then:
-    - **Select `S`**, even if some WIPs have a higher pre-release ordering.
-  - Rationale:
-    - Matches the mental model that **packed stable** is the canonical release.
-    - Useful for CI/production scenarios where stability is preferred.
-
-- **WIP only when stable is not an option**:
-  - If:
-    - No stable versions exist in `available` that satisfy the constraint, but
-    - One or more WIP (or other pre-release) versions do:
-    - The resolver picks the **latest WIP** that satisfies the constraint.
-  - For implicit "latest" / wildcard constraints:
-    - If **any stable versions** exist at all for that package (even if outside the requested range), prefer telling the user to **widen the range** rather than silently pulling a WIP.
-
 ---
 
 ## 6. Behavior per constraint type
 
-### 6.1 Exact versions (incl. exact WIP)
+### 6.1 Exact versions (incl. exact pre-release)
 
-- **Example**: `install foo@1.2.3-000fz8.a3k`.
+- **Example**: `install foo@1.2.3-beta.1`.
 - Behavior:
   - Use **exact match**:
     - If that exact version is in `available`, select it.
     - Otherwise, fail with **“exact version not found”**, show nearby versions.
-  - No additional WIP/stable heuristics are applied.
+  - No additional pre-release/stable heuristics are applied.
 
 ### 6.2 Wildcard / latest (`*`, `latest`)
 
 - **Fresh dependency default (wildcard)**:
-  - For `opkg install <name>` where `<name>` is not yet in `package.yml` and the effective constraint is wildcard/latest:
+  - For `opkg install <name>` where `<name>` is not yet in `openpackage.yml` and the effective constraint is wildcard/latest:
     - Resolution follows the **local-first with remote fallback** policy (see §2 and §7):
       - First, attempt selection using **only local versions** as `available`.
       - If no local versions exist, or none satisfy the wildcard constraint:
         - When remote metadata is available, expand `available` to **`dedup(local ∪ remote)`** and retry selection.
         - Only if **no satisfying version exists in either local or remote**, or remote lookup fails, does the operation error.
 
-- **Default behavior (given an `available` set)**:
+- **Behavior (given an `available` set)**:
   - Use `semver.maxSatisfying(available, '*', { includePrerelease: true })` to find the **highest semver version**.
-  - Select that version (stable or WIP/pre-release).
-  - If the selected version is a pre-release/WIP, the CLI output should make that explicit.
-
-- **With `--stable` flag**:
-  - If **stable versions exist** in `available`, select the **latest stable**.
-  - If **no stable versions exist**:
-    - Select the **latest WIP / pre-release**.
-    - The summary should make it explicit that a **pre-release** was chosen.
+  - Select that version (stable or pre-release).
+  - If the selected version is a pre-release, the CLI output should make that explicit.
 
 ### 6.3 Caret / tilde (`^`, `~`)
 
-- **Default behavior**:
+- **Behavior**:
   - Use `maxSatisfying` with `{ includePrerelease: true }` to find the **highest satisfying version**.
-  - Select that version directly (stable or WIP/pre-release), using the `available` pool determined by the mode and scenario in §2–§3 (including local-first-with-fallback for fresh dependencies).
-
-- **With `--stable` flag**:
-  - Use `maxSatisfying` with `{ includePrerelease: true }` to find the **highest satisfying version**.
-  - Then:
-    - If that best version is **stable**, use it.
-    - If it is **WIP**:
-      - Check whether the **base stable line** of that WIP (`S`) also has a stable version in `available` satisfying the range.
-      - If yes, **pick `S` instead**.
-      - If no, accept the WIP version.
+  - Select that version directly (stable or pre-release), using the `available` pool determined by the mode and scenario in §2–§3 (including local-first-with-fallback for fresh dependencies).
 
 ### 6.4 Comparison ranges
 
-- **Default behavior**:
+- **Behavior**:
   - Use `semver.maxSatisfying(available, range, { includePrerelease: true })` to find the **highest satisfying version**.
-  - Select that version directly (stable or WIP/pre-release), using the `available` pool determined by the mode and scenario in §2–§3 (including local-first-with-fallback for fresh dependencies).
-
-- **With `--stable` flag**:
-  - Same as caret/tilde with `--stable`, but using the exact comparison string.
-  - The stable-preferred rules from §5.3 apply.
+  - Select that version directly (stable or pre-release), using the `available` pool determined by the mode and scenario in §2–§3 (including local-first-with-fallback for fresh dependencies).
 
 ---
 
 ## 7. Local vs remote precedence
 
 - **Default mode**:
-  - For **all dependency resolutions in default mode** (root package and recursive dependencies, whether or not they are already declared in some `package.yml`):
+  - For **all dependency resolutions in default mode** (root package and recursive dependencies, whether or not they are already declared in some `openpackage.yml`):
     - The resolver behaves as **local-first with automatic fallback to remote** as described in §2:
       - It first attempts to satisfy the effective constraint using **local versions only**.
       - If no satisfying local version exists, it **includes remote versions** (when available) and retries selection over the combined set.
       - Only when **neither local nor remote** can satisfy the constraint does it fail with a “no matching versions found” style error.
-  - For **fresh dependencies** (`opkg install <name>` or `opkg install <name>@<spec>` where `<name>` is not yet in `package.yml`, and `--local` is **not** set):
+  - For **fresh dependencies** (`opkg install <name>` or `opkg install <name>@<spec>` where `<name>` is not yet in `openpackage.yml`, and `--local` is **not** set):
     - This is just a special case of the general rule above, where the dependency is being introduced for the first time into the workspace.
 
 - **`--remote` mode**:
@@ -252,65 +208,63 @@ If no version satisfies the constraint:
 These examples assume remote is reachable.
 
 - **Example 1 – Simple caret range**:
-  - `package.yml`: `foo: ^1.2.0`
+  - `openpackage.yml`: `foo: ^1.2.0`
   - Local: `1.2.3`, `1.3.0`
   - Remote: `1.3.1`
   - Selected: **`1.3.1`**.
 
-- **Example 2 – WIP and stable (default behavior)**:
-  - `package.yml`: `foo: ^1.2.0`
-  - Local: `1.2.3-000fz8.a3k`, `1.2.3`, `1.3.0-000fz9.a3k`
+- **Example 2 – Pre-release and stable**:
+  - `openpackage.yml`: `foo: ^1.2.0`
+  - Local: `1.2.3-beta.1`, `1.2.3`, `1.3.0-beta.2`
   - Remote: `1.3.0`
-  - Satisfying: `1.2.3`, `1.3.0-000fz9.a3k`, `1.3.0`
+  - Satisfying: `1.2.3`, `1.3.0-beta.2`, `1.3.0`
   - Selected: **`1.3.0`** (highest semver version).
-  - With `--stable`: **`1.3.0`** (same result, stable preferred).
 
-- **Example 2b – WIP and stable (WIP is newer)**:
-  - `package.yml`: `foo: ^1.2.0`
-  - Local: `1.2.3`, `1.3.0-000fz9.a3k`
+- **Example 2b – Pre-release and stable (pre-release is newer)**:
+  - `openpackage.yml`: `foo: ^1.2.0`
+  - Local: `1.2.3`, `1.3.0-beta.2`
   - Remote: `1.3.0`
-  - Satisfying: `1.2.3`, `1.3.0-000fz9.a3k`, `1.3.0`
-  - Selected (default): **`1.3.0-000fz9.a3k`** (highest semver, even though WIP).
-  - With `--stable`: **`1.3.0`** (stable preferred over WIP).
+  - Satisfying: `1.2.3`, `1.3.0-beta.2`, `1.3.0`
+  - Selected: **`1.3.0-beta.2`** (highest semver, even though pre-release).
 
 - **Example 3 – No stable exists**:
-  - `package.yml`: `foo: ^1.0.0-0` (or explicit WIP version).
+  - `openpackage.yml`: `foo: ^1.0.0-0` (or explicit pre-release).
   - Local: none.
-  - Remote: `1.0.0-000fz8.a3k`, `1.0.1-000fz9.a3k`
-  - Selected: **`1.0.1-000fz9.a3k`**.
+  - Remote: `1.0.0-beta.1`, `1.0.1-beta.1`
+  - Selected: **`1.0.1-beta.1`**.
 
-- **Example 4 – Wildcard with only WIPs**:
+- **Example 4 – Wildcard with only pre-releases**:
   - CLI: `install foo` (fresh dep, default wildcard internally).
   - Local: none.
-  - Remote: `0.1.0-000fz8.a3k`
-  - Selected: **`0.1.0-000fz8.a3k`**, but:
-    - The CLI should make it clear the installed version is a **pre-release/WIP**.
-    - The stored range in `package.yml` may be **exact** or chosen policy-driven (e.g. exact WIP string).
+  - Remote: `0.1.0-beta.1`
+  - Selected: **`0.1.0-beta.1`**, but:
+    - The CLI should make it clear the installed version is a **pre-release**.
+    - The stored range in `openpackage.yml` may be **exact** or chosen policy-driven (e.g. exact pre-release string).
 
 ---
 
-## 9. Content resolution for WIP versions
+## 9. Content resolution for pre-release versions
 
-Version resolution chooses **which version string** to install; this section summarizes how content for **local WIP versions** is sourced, and defers full behavior to `install-behavior.md`.
+Version resolution chooses **which version string** to install; this section summarizes how content for **local pre-release versions** is sourced, and defers full behavior to `install-behavior.md`.
 
-- **Local WIP versions as full copies**:
-  - When the selected version is a WIP that exists locally, it is represented as a **full copied package** in the registry:
-    - Path: `~/.openpackage/registry/<pkg>/<wipVersion>/...`.
+- **Local pre-release versions as full copies**:
+  - When the selected version is a pre-release that exists locally, it is represented as a **full copied package** in the registry:
+    - Path: `~/.openpackage/registry/<pkg>/<version>/...`.
     - The loader must:
       - Load package files directly from that directory.
-      - Read the `package.yml` from that directory for metadata.
-  - The resolved version string (`S-<t>.<w>`) still participates in semver ordering and dependency resolution as specified above.
+      - Read the `openpackage.yml` from that directory for metadata.
+  - The resolved version string still participates in semver ordering and dependency resolution as specified above.
 
-- **Remote WIPs**:
-  - Remote registries are expected to expose **copied artifacts** for any WIP versions they publish.
-  - WIP versions from remote are treated the same as stable versions for content loading (normal registry copies).
+- **Remote pre-releases**:
+  - Remote registries may expose copied artifacts for pre-release versions.
+  - Pre-release versions from remote are treated the same as stable versions for content loading (normal registry copies).
 
 - **Error behavior**:
-  - If a WIP version is selected but its registry directory is missing or malformed:
+  - If a pre-release version is selected but its registry directory is missing or malformed:
     - The install operation should fail with a clear error instead of silently falling back to another version.
     - The error should point to:
-      - The problematic WIP version string.
+      - The problematic version string.
       - The expected registry path.
-      - Suggested remediation (re-save, pack to stable, or choose a different version).
+      - Suggested remediation (re-pack / re-pull, or choose a different version).