opkg 0.5.0 → 0.6.1

package/specs/push/push-behavior.md

@@ -3,7 +3,10 @@
 ### Overview
 
 The `opkg push` command uploads a local package version from the **local registry** to the **remote registry**.
-It is **strictly limited to stable versions** (no prerelease versions like `1.2.3-dev.abc`).
+It allows:
+- **Stable versions** (`x.y.z`).
+- **Unversioned packages** (when `package.yml` omits `version`, represented as `0.0.0`).
+It still rejects prerelease versions like `1.2.3-dev.abc`.
 
 This document focuses on user-facing behavior:
 - CLI shapes and arguments.
@@ -20,11 +23,15 @@ This document focuses on user-facing behavior:
 - **Package syntax**:
   - `<name>` – package name, optionally unscoped.
   - `<name>@<version>` – optional explicit version.
+  - `<name@version>/<registry-path>` – partial push of specific registry paths.
+  - `--paths <list>` – comma-separated registry paths for partial push.
 
 Examples:
 - `opkg push my-pack`
 - `opkg push @scope/my-pack`
 - `opkg push my-pack@1.2.3`
+- `opkg push @scope/my-pack/specs/readme.md` (partial push of a single file)
+- `opkg push @scope/my-pack@1.2.3 --paths specs/readme.md,specs/guide.md`
 
 ---
 
@@ -57,24 +64,25 @@ Examples:
 
 ## Implicit version behavior: `opkg push <pkg>`
 
-When no version is specified, the command **only considers stable versions**.
+When no version is specified, the command prefers **stable versions** and can fall back to a **`0.0.0`** package if no stable exists.
 
 High-level flow:
 
 1. Discover all versions of `<pkg>` from the local registry.
 2. Compute the latest **stable** version.
-3. If no stable versions exist:
+3. If no stable versions exist but a **`0.0.0`** entry exists:
+   - Use the `0.0.0` package as the candidate.
+4. If neither stable nor unversioned exists:
    - Inform the user and exit **gracefully** (non-error).
-4. If a stable version exists:
-   - Prompt the user to confirm pushing that version.
+5. If a candidate exists:
+   - Prompt the user to confirm pushing that candidate.
 
 **Details**
 
-- If no stable versions are found:
-  - The CLI prints:
-    - `❌ No stable versions found for package '<pkg>'`
-    - `💡 Stable versions can be created using "opkg pack <package>".`
-  - The command exits with a **success** result (no global error message).
+- If no stable versions are found but a `0.0.0` entry exists:
+  - The CLI notes it will push the `0.0.0` package.
+- If no stable versions and no unversioned entry:
+  - The CLI prints the existing “no stable versions” message and exits successfully.
 - If a stable version (e.g. `1.2.3`) is found:
   - The CLI prompts:
     - `Push latest stable version '1.2.3'?` (default: yes).
@@ -91,6 +99,26 @@ High-level flow:
 
 ---
 
+## Partial push behavior (paths)
+
+- Partial pushes upload only specific registry paths from an existing local package version.
+- Paths can be provided via:
+  - `<pkg[@ver]>/<registry-path>`
+  - `--paths specs/readme.md,specs/guide.md`
+- Behavior:
+  1. Scope resolution and version selection run first (explicit or latest-stable).
+  2. Requested paths are normalized and validated against the local package files.
+     - Missing paths fail the push with a clear missing-path message.
+  3. Tarball is narrowed to:
+     - The requested file set.
+     - `.openpackage/package.yml`.
+  4. Upload uses the standard `/packages/push` endpoint.
+
+Notes:
+- This replaces the previous single-file `f` flow; single-file pushes are just partial pushes with one path.
+- Manifest is required; if `.openpackage/package.yml` is missing locally, the CLI errors.
+
+
 ## Stable-only guarantees (behavioral view)
 
 From the user’s perspective:

package/specs/push/push-errors-and-hints.md

@@ -79,6 +79,16 @@ The following behavior is preserved from the broader CLI error-handling design,
   - The command returns an error result:
     - `error: "Version not found"`.
 
+### Requested path not found (partial push)
+
+- Condition:
+  - User requests a partial push (via `--paths` or `<pkg@ver>/<registry-path>`) and one or more paths are missing locally.
+- Behavior:
+  - The CLI prints, for each missing path:
+    - `❌ Path '<path>' not found in local registry for '<pkg>@<version>'`
+  - The command returns an error result:
+    - `error: "Requested path not found in local registry"`.
+
 ### Explicit prerelease version
 
 - Condition:
@@ -97,12 +107,15 @@ The following behavior is preserved from the broader CLI error-handling design,
   - User runs `opkg push <pkg>` without specifying a version.
   - No **stable** versions of `<pkg>` exist in the local registry.
 - Behavior:
-  - The CLI prints:
-    - `❌ No stable versions found for package '<pkg>'`
-    - `💡 Stable versions can be created using "opkg pack <package>".`
-  - The command returns a **success** result (no error string), so the global error handler:
-    - Does **not** print an additional plain `No stable versions found` line.
-  - This is treated as an informational exit: the user simply needs to create a stable version first.
+  - If a **`0.0.0`** entry exists:
+    - The CLI attempts to push the `0.0.0` package.
+  - If no `0.0.0` entry exists:
+    - The CLI prints:
+      - `❌ No stable versions found for package '<pkg>'`
+      - `💡 Stable versions can be created using "opkg pack <package>".`
+    - The command returns a **success** result (no error string), so the global error handler:
+      - Does **not** print an additional plain `No stable versions found` line.
+    - This is treated as an informational exit: the user needs to create a stable (or unversioned) package first.
 
 ---
 

package/specs/push/push-remote-upload.md

@@ -41,6 +41,9 @@ Assuming a valid stable package `pkg` and `versionToPush` have been selected:
 4. **Tarball creation**
 
    - `createTarballFromPackage(pkg)` builds a tarball from the package files.
+   - For **partial pushes** (paths provided via spec or `--paths`):
+     - The tarball is narrowed to only the requested registry paths plus `.openpackage/package.yml`.
+     - File count reflects only the selected files.
    - The CLI prints:
      - `✓ Creating tarball...`
      - `✓ Created tarball (<file-count> files, <formatted-size>)`

package/specs/push/push-scoping.md

@@ -5,44 +5,36 @@
 The `opkg push` command may need to **scope** an unscoped package before pushing it.
 Scoping ensures that packages in the remote registry are properly namespaced, e.g. `@user/package`.
 
-This document describes how `push` handles scoping and how it keeps the local registry and workspace in sync.
+This document describes how `push` handles scoping for upload. Scoping is applied **only to the upload payload**; the local registry and workspace stay unchanged.
 
 ---
 
-## Scope handling
+## Scope handling (upload-only)
 
-1. The command looks up `<package-name>` in the local registry.
+1. The command looks up `<package-name>` in the local registry using the **input name** (unscoped is allowed).
 2. If the name is **unscoped** (e.g. `test`):
    - Authentication is validated using the provided profile/API key.
    - The current username (or profile’s default scope) is resolved.
-   - A scoped name is computed (e.g. `@user/test`).
-   - The local registry package is renamed to the scoped name using `renameRegistryPackage`.
-   - The workspace package is updated (where possible) using `tryRenameWorkspacePackage`, so:
-     - `package.yml` and related workspace configuration reflect the new scoped name.
-3. After scoping:
-   - **All further logic** (version resolution, checks, push) operates on the **scoped name**.
+   - A scoped upload name is computed (e.g. `@user/test`) via the existing prompt/default-scope flow.
+   - No local rename occurs; the local registry and workspace remain on the unscoped name.
+3. Before tarball creation:
+   - The package is cloned in-memory and its `.openpackage/package.yml` `name` field is rewritten to the scoped upload name.
+   - The upload payload (full or partial) uses this in-memory manifest, so the remote receives the scoped identity.
+4. Version selection and path validation still operate on the local name and local files.
 
 ---
 
 ## Invariants
 
-- After a successful scope operation:
-  - The local registry no longer stores the unscoped name as the active location.
-  - The scoped name (e.g. `@user/test`) is the canonical identity used by:
-    - Version selection.
-    - Tarball creation.
-    - Remote upload.
-- The workspace is updated where possible so that:
-  - Future `save`, `pack`, and `push` operations use the scoped name naturally.
-  - References within the workspace (e.g. `package.yml`) do not drift from the registry identity.
+- The local registry and workspace are **not** renamed by `push`; the unscoped layout remains intact.
+- The upload payload always carries a scoped name (manifest rewritten in-memory) when pushing an unscoped package.
+- Version selection and missing-path validation use the local name and files; only the upload name changes for remote interaction.
 
 ---
 
 ## Relationship to version selection
 
-- Scoping happens **before** version selection.
-- Once the package name is scoped:
-  - All lookups for versions (`listPackageVersions`, `packageManager.loadPackage`) use the scoped name.
-  - The version-selection rules (see `push-version-selection.md`) are applied strictly to the scoped name.
+- Scoping for upload is determined before version selection, but local lookups use the **input name**.
+- Version selection (`listPackageVersions`, `packageManager.loadPackage`) is driven by the local name; only the upload payload uses the scoped name.
 
 

package/specs/push/push-version-selection.md

@@ -1,9 +1,10 @@
-## Push version selection (stable-only)
+## Push version selection (stable + unversioned)
 
 ### Terminology
 
 - **Stable version**: A semver-valid version with no prerelease segment, e.g. `1.2.3`.
 - **Prerelease version**: A semver-valid version with a prerelease segment, e.g. `1.2.3-dev.abc123`.
+- **Unversioned package**: A package whose `package.yml` omits `version`; represented and stored as semver `0.0.0` locally (one per package) and can be pushed like any other stable version.
 - **Local registry**: The on-disk package store used by `opkg` (managed via `packageManager`).
 
 This document defines the rules `opkg push` uses to decide **which local version** is eligible to be pushed to the remote registry.
@@ -29,8 +30,7 @@ Given `<pkg>@<version>`:
 
 3. **Safety check**
    - After loading, the resulting `pkg.metadata.version` must still be stable.
-   - If it is not (should only occur in pathological cases):
-     - The push is rejected as if a prerelease was requested.
+   - If it is not (pathological), the push is rejected as a prerelease.
 
 **Result**
 
@@ -42,11 +42,12 @@ Given `<pkg>@<version>`:
 
 ## Implicit version: `opkg push <pkg>`
 
-When no version is explicitly supplied, `opkg push` must:
+When no version is explicitly supplied, `opkg push`:
 
-- Consider **all local versions** of `<pkg>`.
-- Select the **latest stable version** only.
-- Treat the absence of stable versions as a **non-error** (informational) outcome.
+- Considers **all local versions** of `<pkg>`.
+- Prefers the **latest stable** version.
+- If no stable exists but a `0.0.0` entry exists, uses that entry.
+- Treats absence of both stable and `0.0.0` as a **non-error** (informational) outcome.
 
 ### Algorithm
 
@@ -61,28 +62,29 @@ Let `versions = listPackageVersions(pkg)` (all local versions, as directory name
      - Otherwise, returns the highest stable version using `semver.rsort`.
 
 2. If `latestStable === null`:
-   - There is **no stable version** to push.
-   - The CLI prints a “no stable versions found” message and a hint to use `opkg pack`.
-   - The command exits with a **success** result (no error propagated to the global handler).
+   - No semver-stable versions exist (including `0.0.0`), so:
+     - Print the “no stable versions” message and exit with success.
 
-3. If `latestStable` is present:
+3. If `latestStable` is present (including the case where it is `0.0.0`):
    - That version becomes the candidate `versionToPush`.
    - The user is asked to confirm before pushing (see behavior spec).
 
 **Notes**
 
-- Prerelease-only packages (e.g. `1.0.0-dev.abc`, `1.0.0-dev.def`) result in `latestStable === null`.
+- Prerelease-only packages (e.g. `1.0.0-dev.abc`, `1.0.0-dev.def`) result in `latestStable === null`; if an unversioned entry exists, it is chosen, otherwise informational exit.
 - Mixed stable and prerelease sets (e.g. `1.0.0`, `1.1.0-dev.abc`, `1.2.0`) always choose the numerically highest stable (`1.2.0`).
 
 ---
 
-## Stable-only guarantees (versioning view)
+## Stable/unversioned guarantees (versioning view)
 
 From the version-selection point of view:
 
-- `push` **never** picks a prerelease version as `versionToPush`.
+- `push` **never** picks a prerelease version.
 - Explicit prerelease inputs are rejected up front.
-- Implicit selection ignores all prerelease versions when computing candidates.
-- Existing helper functions (`filterStableVersions`, `getLatestStableVersion`) centralize the definition of “stable”.
+- Implicit selection:
+- Prefers latest stable (with `0.0.0` treated as a normal stable version).
+- `0.0.0` pushes are treated the same as other stable versions.
+  - Ignores prereleases for candidacy.
 
 

package/specs/save/README.md

@@ -0,0 +1,40 @@
+### Save Pipeline Specs
+
+This directory contains specifications for the **save pipeline** that powers both the `save` (WIP) and `pack` (stable) commands.
+
+These docs are **behavioral**: they describe features and logic, not specific modules or functions.
+
+---
+
+#### Pipeline Flow
+
+The save pipeline executes in this order:
+
+1. **Modes & Inputs** → Determine WIP vs stable mode and parse flags
+2. **Package Detection** → Find the target package context
+3. **Naming & Scoping** → Resolve final name, handle renames
+4. **File Discovery** → Discover candidate files from local and workspace
+5. **Conflict Resolution** → Decide which content wins for each path
+6. **Frontmatter & Overrides** → Handle markdown metadata and platform overrides
+7. **Registry & Sync** → Write to registry, cleanup, and sync to platforms
+
+---
+
+#### Files
+
+| File | Topic |
+|------|-------|
+| `save-modes-inputs.md` | Overview, WIP vs stable modes, inputs, and flags |
+| `save-package-detection.md` | How the pipeline detects which package to operate on |
+| `save-naming-scoping.md` | Name resolution, scoping decisions, and workspace renames |
+| `save-file-discovery.md` | Candidate sources, first vs subsequent saves, grouping |
+| `save-conflict-resolution.md` | Conflict resolution rules and platform-specific selection |
+| `save-frontmatter-overrides.md` | Markdown frontmatter extraction and YAML overrides |
+| `save-registry-sync.md` | Registry writes, WIP cleanup, and platform sync |
+
+---
+
+#### Related Documents
+
+- `../save-pack.md` – High‑level split between `save` and `pack` commands.
+- `../save-pack-versioning.md` – Detailed versioning rules for WIP and stable versions.

package/specs/save/save-conflict-resolution.md

@@ -0,0 +1,146 @@
+### Save Pipeline – Conflict Resolution
+
+#### 1. Overview
+
+When multiple candidates exist for the same registry path, the pipeline must decide which content to use. This document describes the conflict resolution rules.
+
+---
+
+#### 2. Resolution Goals
+
+For each group, the pipeline decides:
+
+- Whether any action is needed (no-op when everything matches).
+- Which content becomes the **universal** package content for that registry path.
+- Which workspace candidates, if any, should be treated as **platform‑specific** sidecars.
+
+---
+
+#### 3. Conflict Types
+
+There are two main flavors of groups:
+
+1. **Root conflicts** (root documentation file for the package)
+2. **Regular conflicts** (all other paths)
+
+---
+
+#### 4. Root Conflicts
+
+For the root package section file (e.g. the unified agents document):
+
+##### Ordering and deduplication
+
+- The pipeline orders candidates roughly by:
+  - Existing local content first (if any).
+  - Workspace candidates by newest modification time, then by display path.
+- Deduplicates candidates by content hash.
+
+##### Single candidate
+
+- If there is exactly one unique candidate:
+  - That candidate is used as the universal content for the root file.
+
+##### Multiple differing candidates
+
+- If the local candidate is newer than or equal to all workspace candidates:
+  - The local candidate is selected automatically.
+- Otherwise:
+  - With `--force`:
+    - The local candidate always wins.
+  - Without `--force`:
+    - The user is prompted to choose which candidate should become the universal root content.
+
+##### Output
+
+- The chosen root content is written into the package's root file location.
+- Platform‑specific root selections (e.g. separate root files for individual platforms) are persisted as separate package files where appropriate.
+
+---
+
+#### 5. Regular Conflicts
+
+For non‑root paths:
+
+##### Ordering and deduplication
+
+- The pipeline again orders and deduplicates candidates.
+- Checks whether any workspace candidate actually **differs** from the local candidate.
+
+##### No local candidate
+
+- If the file does not yet exist in the package:
+  - The selected workspace candidate becomes the new file content.
+
+##### Identical content
+
+- If local and all workspace candidates have identical content:
+  - The group is skipped (no changes).
+
+##### Differences with local candidate
+
+When there are differences and a local candidate exists:
+
+- If the local candidate is newer or as new as any workspace candidate:
+  - The local version wins silently (no prompt).
+- If a newer workspace candidate exists:
+  - Without `--force`:
+    - The user is prompted to choose which candidate should become universal content.
+  - With `--force`:
+    - The local candidate wins even if workspace content is newer.
+
+---
+
+#### 6. Resolution Principles
+
+In all cases, the goal is to:
+
+- Prefer local content when it is at least as new as workspace content.
+- Ask the user only when a newer workspace change would override local content.
+- Respect an explicit `--force` override in favor of local content.
+
+---
+
+#### 7. Platform‑Specific Selection
+
+Some workspace candidates are associated with specific platforms (e.g. platform‑specific variants of a shared file).
+
+##### Marking platform-specific candidates
+
+- Before choosing the universal content, the user can be offered a chance to:
+  - Mark one or more workspace candidates as **platform‑specific**.
+  - These marked candidates will be written to platform‑specific registry paths instead of becoming the universal content.
+
+##### After marking
+
+- The remaining candidates (local + unmarked workspace candidates) participate in universal conflict resolution as described above.
+- Marked candidates are saved as platform‑specific sidecars if they are not chosen as the universal content.
+
+##### Use case
+
+This mechanism lets a user:
+
+- Keep a single universal file.
+- Simultaneously maintain richer, platform‑specific versions where needed.
+
+---
+
+#### 8. Escalation from YAML Overrides to Full Platform Markdown
+
+When a registry path participates in the frontmatter/YAML override pipeline (e.g. `.openpackage/agents/*.md`) **and** the user marks one or more workspace candidates as platform‑specific during conflict resolution:
+
+- **Universal body update**
+  - The universal markdown file keeps its existing frontmatter.
+  - If the selected universal candidate’s body differs, only the **markdown body** is updated.
+  - Frontmatter for that path continues to be managed by the YAML override pipeline.
+
+- **Escalating a platform to full `.platform.md`**
+  - Each marked platform‑specific workspace candidate is written to a platform‑specific markdown path (e.g. `yaml-test.qwen.md`) using the **full candidate content** (frontmatter + body).
+  - For root conflicts, only the section body is used (consistent with root handling elsewhere).
+
+- **Interaction with YAML overrides**
+  - If a platform has an existing YAML override file (e.g. `yaml-test.qwen.yml`) and is escalated to a full `.platform.md`:
+    - The corresponding YAML override file is removed as redundant.
+    - That platform is removed from the frontmatter merge plan for that registry path.
+  - After escalation, the remaining frontmatter/YAML plans (if any) are applied only for platforms that still use YAML overrides, ensuring universal frontmatter is not recomputed based on escalated full‑markdown variants.
+

package/specs/save/save-file-discovery.md

@@ -0,0 +1,101 @@
+### Save Pipeline – File Discovery
+
+#### 1. Overview
+
+Before copying a package into the registry, the save pipeline must decide **which files and content** belong to the package. This document covers how candidate files are discovered and organized.
+
+---
+
+#### 2. Candidate Sources
+
+For each save/pack run, the pipeline considers up to four sets of candidates:
+
+##### Local platform candidates
+
+- Files already present in the **package directory** under `.openpackage/packages/<name>/`.
+- Excludes:
+  - Internal `package.index.yml` metadata.
+  - Certain root marker files (e.g. the unified root agents file) that are handled specially.
+- Only includes paths that are allowed by the registry path rules (e.g. skip internal or unsupported paths).
+
+##### Workspace platform candidates
+
+- Files discovered in the **workspace** that can map into package registry paths (e.g. documentation, rules, platform‑specific content).
+- Each discovered file carries:
+  - A target registry path.
+  - Its full workspace path.
+  - A modification time (mtime).
+  - Optional platform tag (e.g. a specific platform associated with that file).
+
+##### Local root candidates
+
+- Root‑level documentation files that already exist as part of the package (e.g. `AGENTS.md` or platform‑specific root docs in the package directory).
+- Represent root **sections** for a package inside a shared root file.
+
+##### Workspace root candidates
+
+- Root‑level files in the workspace (outside the package directory) that contain dedicated sections for packages.
+- These are discovered and turned into candidates representing just the **package's section body** within the larger root file.
+
+---
+
+#### 3. Candidate Properties
+
+Each candidate includes:
+
+- Its **source** (`local` vs `workspace`).
+- The **registry path** it maps to.
+- The file content (or section body, for root candidates).
+- A content hash for deduplication.
+- The last modification time.
+- Optional **platform** information for platform‑specific variants.
+
+---
+
+#### 4. First Save vs Subsequent Saves
+
+The behavior changes depending on whether the package already has an index (`package.index.yml`) with file mapping information.
+
+##### First save (no index present, or empty file mapping)
+
+- The pipeline focuses on **root files** (shared documentation).
+- It:
+  - Groups local root candidates and workspace root candidates by registry path.
+  - Prompts the user where needed to resolve differences.
+  - Writes a unified root file (e.g. `AGENTS.md`) plus any platform‑specific copies.
+- The final set of files for the package snapshot is simply the filtered contents of the package directory after root conflicts have been resolved.
+
+##### Subsequent saves (index present with file mappings)
+
+- The pipeline uses `package.index.yml` as a **filter** for which workspace paths are relevant:
+  - It builds a set of allowed registry paths and directories based on the index's `files` keys.
+  - Workspace candidates whose registry paths are outside this allowed set are ignored, except for root files that are deliberately allowed.
+- It merges local and workspace candidates:
+  - Local platform candidates.
+  - Local root candidates.
+  - Workspace platform candidates filtered by allowed registry paths.
+  - Workspace root candidates filtered similarly.
+- These merged candidates are then grouped and passed through conflict resolution.
+
+This split ensures that:
+
+- The **first** save can safely bootstrap root files and initial content.
+- Later saves don't accidentally pull in arbitrary workspace files that were never part of the package.
+
+---
+
+#### 5. Grouping Candidates by Registry Path
+
+For conflict resolution, the pipeline groups candidates by their **normalized registry path**:
+
+- Each **group** contains:
+  - At most one `local` candidate (the current package content for that path).
+  - Zero or more `workspace` candidates (workspace versions mapping to the same path).
+- Root and non‑root paths are handled in the same grouping mechanism, but root groups get special conflict rules (see `save-conflict-resolution.md`).
+
+Grouping allows the pipeline to reason about each registry path independently:
+
+- Whether it has only local content, only workspace content, or both.
+- Whether workspace content is identical to or different from the local content.
+- Whether there are platform‑specific workspace choices for that path.
+

package/specs/save/save-frontmatter-overrides.md

@@ -0,0 +1,81 @@
+### Save Pipeline – Frontmatter and YAML Overrides
+
+#### 1. Overview
+
+For markdown files, the pipeline manages **frontmatter** and platform‑specific overrides to keep shared metadata centralized while allowing platform-specific behavior.
+
+---
+
+#### 2. Workspace Markdown Candidates
+
+- For each platform, the latest workspace markdown candidate for a given registry path is considered.
+- The frontmatter is normalized and separated from the markdown body.
+
+---
+
+#### 3. Universal Frontmatter Extraction
+
+- The pipeline computes frontmatter keys and values that are **identical across all platform entries** for that path.
+- These shared keys form the **universal frontmatter** that should live in the base markdown file.
+
+---
+
+#### 4. Platform‑Specific Overrides
+
+For each platform:
+
+- The per‑platform frontmatter is compared against the universal frontmatter.
+- Only the **difference** per platform is treated as that platform's override, or omitted if empty.
+- Platform overrides are written into **separate YAML files** in a dedicated overrides location.
+
+---
+
+#### 5. Conflicts with Existing Overrides
+
+When a platform override file already exists for a path:
+
+- The pipeline compares existing and new frontmatter, taking modification times into account.
+- Typically:
+  - If the newer change comes from the workspace, it is preferred by default.
+  - When there is a conflicting but not clearly newer override, the user may be prompted to choose between workspace and existing override content where appropriate.
+
+---
+
+#### 6. Resulting Layout
+
+- One universal markdown file with shared frontmatter.
+- Zero or more per‑platform YAML override files capturing only the per‑platform differences.
+
+This scheme keeps:
+
+- Shared metadata centralized in the universal file.
+- Platform‑specific behavior in small, explicit override files.
+- Markdown bodies free from duplication where possible.
+
+---
+
+#### 7. Final File Inclusion Rules
+
+After all conflicts and frontmatter merges are resolved, the pipeline reads the final contents of the package directory and applies a last round of filtering.
+
+##### Excluded
+
+- `package.index.yml`.
+- Internal files that are not considered part of the package content.
+
+##### Included
+
+- Paths allowed by the regular registry path rules.
+- Root files (the unified root agents file and related root docs).
+- YAML override files that represent platform‑specific metadata.
+- Root‑level files adjacent to `package.yml` that are intended as part of the package.
+
+---
+
+#### 8. Output
+
+The resulting list of files, with paths relative to the package directory, is what gets:
+
+- Copied into the local registry under the computed version.
+- Used to drive platform sync and any subsequent operations in the save pipeline.
+