wavefnd · LunaStev · Aug 23, 2026 · Aug 23, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -185,7 +185,7 @@ jobs:
           gh release create "$RELEASE_TAG" \
             --verify-tag \
             --draft \
-            --generate-notes \
+            --notes-file RELEASE_NOTES.md \
             --title "Vex $RELEASE_TAG" \
             dist/vex-*.tar.gz \
             dist/vex-*.zip \

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to Vex are documented in this file. Vex follows Semantic
+Versioning while the public command and lockfile contracts are still maturing.
+
+## [0.0.1] - 2026-08-23
+
+### Added
+
+- Manifest-based `init`, `build`, `run`, `check`, `fetch`, `update`, `info`, and
+  `setup wavec` commands for Wave projects.
+- Recursive Git and path dependency resolution with cycle, package-name,
+  source, and version conflict detection.
+- `vex.lock` schema v2, which records exact Git object IDs and dependency graph
+  edges so a manifest and lockfile reproduce the same dependency graph.
+- Full and package-targeted Git updates. `vex update <package>...` preserves
+  unrelated locked commits and accepts directly or transitively referenced
+  package names.
+- `--locked` and `--offline` dependency modes, including their combined use.
+- Cargo-style progress reporting and actionable dependency errors.
+- `wavec` discovery through `PATH`, an explicit `VEX_WAVEC` override, and
+  validation of the compiler dry-run JSON schema v1 contract.
+- Reproducible release archives for Linux amd64/arm64/RISC-V, Windows x64, and
+  macOS Intel/Apple Silicon, with SHA-256 checksums and GitHub provenance
+  attestations.
+
+### Fixed and hardened
+
+- Path dependency locations are stored relative to the project when possible,
+  so the same relative package tree and lockfile can move together.
+- Help is read-only and succeeds without a manifest; invalid `init`, `info`,
+  target, and global command arguments now fail consistently.
+- Git object IDs loaded from a lockfile must be complete hexadecimal IDs.
+- Git clone and revision commands terminate option parsing, Git's external
+  transport protocol is disabled for managed operations, and symbolic links
+  cannot redirect the managed `.vex/deps` area outside the project.
+- The downloaded `wavec` installer uses exclusive, uniquely named temporary
+  files and removes them after execution.
+- Release archives carry a lockfile-checked inventory of third-party licenses
+  and copyright notices.
+
+### Compatibility notes
+
+- Lockfiles produced by development snapshots may contain absolute path
+  dependency locations. Run `vex fetch` once to rewrite those entries before
+  using `--locked` with v0.0.1.
+- Vex has been tested with `wavec 0.2.0-pre-beta`. The authoritative compiler
+  compatibility check is support for `build --dry-run --error-format=json`
+  schema version 1.
+- A central registry, publishing, workspaces, `vex add`/`vex remove`, and a
+  global Git cache are not part of v0.0.1.
+
+[0.0.1]: https://github.com/wavefnd/Vex/releases/tag/v0.0.1
diff --git a/Cargo.toml b/Cargo.toml
@@ -2,6 +2,13 @@
 name = "vex"
 version = "0.0.1"
 edition = "2021"
+description = "Package manager and build tool for the Wave programming language"
+license = "MPL-2.0"
+repository = "https://github.com/wavefnd/Vex"
+readme = "README.md"
+keywords = ["wave", "package-manager", "build-tool"]
+categories = ["command-line-utilities", "development-tools::build-utils"]
+publish = false
 
 [dependencies]
 wson_rs = "0.2.5"

diff --git a/NOTICE b/NOTICE
@@ -13,7 +13,8 @@ copyright information.
 Vex invokes the separately distributed `wavec` compiler. The Vex source and
 release archives do not grant additional rights to `wavec`, Wave packages, or
 third-party dependencies; those works remain subject to their respective
-licenses.
+licenses. The locked dependency inventory, copyright attributions, and
+applicable license notices are provided in THIRD_PARTY_LICENSES.md.
 
 Source code for this release is available from:
 https://github.com/wavefnd/Vex
diff --git a/README.md b/README.md
@@ -6,12 +6,15 @@ Vex is designed to sit above `wavec` in the same way Cargo sits above `rustc`: V
 
 ## Requirements
 
-- Rust toolchain for building Vex from source
 - `wavec` compatible with the `build --dry-run --error-format=json` schema v1 contract
 - `git` when using Git dependencies
+- Rust toolchain only when building Vex from source
 - Python 3.11 or newer when using the release tooling
 
 Vex runs `wavec` from `PATH` by default. Set `VEX_WAVEC=/path/to/wavec` to use a specific compiler binary.
+Vex v0.0.1 is tested with `wavec 0.2.0-pre-beta`; support for schema v1 is the
+authoritative compatibility requirement. Vex reports a schema mismatch before
+the real build and suggests selecting another compiler with `VEX_WAVEC`.
 
 ## Platform validation
 
@@ -31,8 +34,51 @@ the release workflow also passes package and clean-environment smoke tests.
 Windows release artifacts use the MSVC target. A Windows GNU artifact is not
 part of the v0.0.1 scope. RISC-V remains experimental because its test coverage
 is limited to cross-build and QEMU smoke rather than the complete integration
-suite. Final minimum OS and glibc versions will be fixed by the release workflow
-before v0.0.1 is tagged.
+suite.
+
+The v0.0.1 Linux GNU archives are built on Ubuntu 24.04 and require a glibc-based
+system; Ubuntu 24.04 is the supported runtime baseline. Windows artifacts are
+validated on the GitHub Windows Server 2025 runner, and macOS artifacts on
+macOS 15. Older operating systems and other distributions are best effort for
+this first release.
+
+## Install
+
+Download the archive and `SHA256SUMS` for your platform from the
+[GitHub release](https://github.com/wavefnd/Vex/releases/tag/v0.0.1). Verify the
+download before extracting it:
+
+```sh
+sha256sum --check SHA256SUMS
+tar -xzf vex-v0.0.1-x86_64-unknown-linux-gnu.tar.gz
+install -m 0755 vex-v0.0.1-x86_64-unknown-linux-gnu/vex ~/.local/bin/vex
+vex --version
+```
+
+On Windows, compare `Get-FileHash <archive> -Algorithm SHA256` with the matching
+line in `SHA256SUMS`, extract the zip, and place `vex.exe` in a directory on
+`PATH`. GitHub CLI can additionally verify the published provenance:
+
+```sh
+gh attestation verify vex-v0.0.1-x86_64-unknown-linux-gnu.tar.gz \
+  --repo wavefnd/Vex
+```
+
+To build from source instead:
+
+```sh
+git clone https://github.com/wavefnd/Vex.git
+cd Vex
+cargo build --locked --release
+install -m 0755 target/release/vex ~/.local/bin/vex
+```
+
+Install `wavec` separately and make it available on `PATH`, or set
+`VEX_WAVEC` to its full path. `vex setup wavec` is an explicit convenience
+command that downloads and executes the official installer from
+`wave-lang.dev`; review that trust and network boundary before using it. A
+specific compiler can be requested with `vex setup wavec --version
+0.2.0-pre-beta`.
 
 ## Commands
 
@@ -179,10 +225,11 @@ python3 x.py package x86_64-unknown-linux-gnu
 python3 x.py checksum x86_64-unknown-linux-gnu
 ```
 
-Archives contain the Vex executable together with `README.md`, `LICENSE`,
-`NOTICE`, and `COPYRIGHT`. Their file order, permissions, owners, and timestamps
-are normalized. Set `SOURCE_DATE_EPOCH` to an explicit non-negative Unix
-timestamp when reproducing an artifact outside the tagged source revision.
+Archives contain the Vex executable together with `README.md`, `CHANGELOG.md`,
+`LICENSE`, `NOTICE`, `COPYRIGHT`, and `THIRD_PARTY_LICENSES.md`. Their file
+order, permissions, owners, and timestamps are normalized. Set
+`SOURCE_DATE_EPOCH` to an explicit non-negative Unix timestamp when reproducing
+an artifact outside the tagged source revision.
 
 `python3 x.py release [<target>...]` is intentionally stricter than separate
 build and package commands. It runs the complete validation suite and succeeds
@@ -222,6 +269,9 @@ gh attestation verify vex-v0.0.1-x86_64-unknown-linux-gnu.tar.gz \
 - [Maintainers](MAINTAINERS)
 - [Security Policy](SECURITY.md)
 - [Release Process](RELEASING.md)
+- [v0.0.1 Release Notes](RELEASE_NOTES.md)
+- [Changelog](CHANGELOG.md)
 - [Copyright](COPYRIGHT)
 - [Notice](NOTICE)
+- [Third-party licenses](THIRD_PARTY_LICENSES.md)
 - [AI Usage Policy](ai.txt)
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -0,0 +1,57 @@
+# Vex v0.0.1
+
+Vex v0.0.1 is the first public release of the package manager and build tool
+for the Wave programming language. It establishes the manifest, dependency,
+lockfile, compiler, and release contracts that future versions will build on.
+
+## Highlights
+
+- Create and inspect `vex.ws` projects with `vex init` and `vex info`.
+- Build, check, and run Wave packages while Vex manages the internal `wavec`
+  invocation.
+- Resolve recursive Git and path dependencies and record the complete graph in
+  `vex.lock` schema v2.
+- Reproduce exact Git commits with `--locked`, prohibit Git network access with
+  `--offline`, or combine both modes for strict CI builds.
+- Refresh the whole Git graph with `vex update`, or update direct and transitive
+  packages selectively with `vex update <package>...` while preserving
+  unrelated commits.
+- Download reproducible archives with SHA-256 checksums and GitHub build
+  provenance for Linux amd64/arm64/RISC-V, Windows x64, and macOS Intel/Apple
+  Silicon.
+
+## Compiler compatibility
+
+Vex v0.0.1 is tested with `wavec 0.2.0-pre-beta`. A compatible compiler must
+support `wavec build --dry-run --error-format=json` schema version 1. Vex finds
+`wavec` on `PATH` by default; use `VEX_WAVEC=/path/to/wavec` to select another
+binary.
+
+## Verify before installing
+
+Download the archive for your target together with `SHA256SUMS`, then run:
+
+```sh
+sha256sum --check SHA256SUMS
+gh attestation verify <archive> --repo wavefnd/Vex
+```
+
+Linux GNU archives use Ubuntu 24.04 as their supported runtime baseline.
+Windows x64 is validated on Windows Server 2025 and macOS archives on macOS 15.
+The RISC-V archive is experimental and receives cross-build plus QEMU smoke
+coverage rather than the complete native integration suite.
+
+## Known scope
+
+This release intentionally has no central registry, publishing command,
+workspace support, `vex add`/`vex remove`, or global Git cache. Raw `wavec`
+options are not accepted by Vex commands.
+
+Development lockfiles containing absolute path dependency locations should be
+rewritten once with `vex fetch` before using `--locked` with v0.0.1. See the
+[changelog](https://github.com/wavefnd/Vex/blob/v0.0.1/CHANGELOG.md) and
+[installation guide](https://github.com/wavefnd/Vex/blob/v0.0.1/README.md#install)
+for full details.
+
+Thank you to every contributor and tester who helped establish Vex's first
+reproducible package-management and release baseline.
diff --git a/RELEASING.md b/RELEASING.md
@@ -22,17 +22,33 @@ GitHub Release. It never publishes a release automatically.
 Start from the current `wavefnd/Vex:master`. Complete the release-candidate
 checklist before tagging:
 
-1. Update `CHANGELOG.md` and user-facing release notes.
+1. Update `CHANGELOG.md` and the reviewed `RELEASE_NOTES.md` used by the release
+   workflow.
 2. Confirm the supported platform table and compatible `wavec` contract.
 3. Confirm that `Cargo.toml` contains the intended version and that
    `Cargo.lock` is committed.
-4. Run the complete local validation suite:
+4. Audit the locked Rust dependency graph for known vulnerabilities and review
+   every dependency license. Record the scanner, advisory database date, and
+   result in the pull request. For example, OSV-Scanner v2 can inspect the
+   committed lockfile with:
+
+   ```sh
+   osv-scanner scan source --lockfile Cargo.lock
+   cargo metadata --locked --format-version 1
+   ```
+
+5. Run the complete local validation suite:
 
    ```sh
    python3 x.py check
    ```
 
-5. Merge the release-candidate pull request and wait for every required CI
+6. Run a real product smoke with a compatible `wavec`: initialize a temporary
+   project, run Hello World through `PATH`, repeat a locked/offline build, and
+   confirm a raw compiler option such as `vex build --emit=obj` is rejected.
+   The integration suite must also cover path-lock relocation, Git lock
+   reproducibility, full and targeted updates, and compiler schema rejection.
+7. Merge the release-candidate pull request and wait for every required CI
    check on `master` to pass.
 
 Do not create a release tag from a feature branch, a dirty checkout, or a
@@ -95,7 +111,9 @@ gh attestation verify vex-v0.0.1-x86_64-unknown-linux-gnu.tar.gz \
 Repeat attestation verification for every archive and `SHA256SUMS`. Extract at
 least one native archive in a clean environment and run `vex --version` and
 `vex --help`. Complete the documented Wave project smoke test with a compatible
-`wavec` before publication.
+`wavec` before publication. Confirm that each archive also contains
+`README.md`, `CHANGELOG.md`, `LICENSE`, `NOTICE`, `COPYRIGHT`, and
+`THIRD_PARTY_LICENSES.md`.
 
 ## 4. Publish deliberately
 

diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md
@@ -0,0 +1,85 @@
+# Third-party software notices
+
+Vex binaries include software from the Rust packages below. Versions are fixed
+by `Cargo.lock`; links identify the corresponding source distributions and
+their complete license files. This inventory was generated from Cargo metadata
+for v0.0.1.
+
+| Packages | Version(s) | Declared license |
+| --- | --- | --- |
+| [aho-corasick](https://crates.io/crates/aho-corasick/1.1.4), [memchr](https://crates.io/crates/memchr/2.8.0) | 1.1.4, 2.8.0 | Unlicense OR MIT |
+| [android_system_properties](https://crates.io/crates/android_system_properties/0.1.5) | 0.1.5 | MIT OR Apache-2.0 |
+| [autocfg](https://crates.io/crates/autocfg/1.5.0), [bumpalo](https://crates.io/crates/bumpalo/3.20.2), [cc](https://crates.io/crates/cc/1.2.57), [cfg-if](https://crates.io/crates/cfg-if/1.0.4) | 1.5.0, 3.20.2, 1.2.57, 1.0.4 | MIT OR Apache-2.0 |
+| [chrono](https://crates.io/crates/chrono/0.4.44), [core-foundation-sys](https://crates.io/crates/core-foundation-sys/0.8.7) | 0.4.44, 0.8.7 | MIT OR Apache-2.0 |
+| [colorex](https://crates.io/crates/colorex/0.1.2), [wson_rs](https://crates.io/crates/wson_rs/0.2.5) | 0.1.2, 0.2.5 | MPL-2.0 |
+| [find-msvc-tools](https://crates.io/crates/find-msvc-tools/0.1.9), [iana-time-zone](https://crates.io/crates/iana-time-zone/0.1.65), [iana-time-zone-haiku](https://crates.io/crates/iana-time-zone-haiku/0.1.2) | 0.1.9, 0.1.65, 0.1.2 | MIT OR Apache-2.0 |
+| [itoa](https://crates.io/crates/itoa/1.0.18), [js-sys](https://crates.io/crates/js-sys/0.3.91), [libc](https://crates.io/crates/libc/0.2.183), [log](https://crates.io/crates/log/0.4.29) | 1.0.18, 0.3.91, 0.2.183, 0.4.29 | MIT OR Apache-2.0 |
+| [num-traits](https://crates.io/crates/num-traits/0.2.19), [once_cell](https://crates.io/crates/once_cell/1.21.4), [proc-macro2](https://crates.io/crates/proc-macro2/1.0.106), [quote](https://crates.io/crates/quote/1.0.45) | 0.2.19, 1.21.4, 1.0.106, 1.0.45 | MIT OR Apache-2.0 |
+| [regex](https://crates.io/crates/regex/1.12.3), [regex-automata](https://crates.io/crates/regex-automata/0.4.14), [regex-syntax](https://crates.io/crates/regex-syntax/0.8.10) | 1.12.3, 0.4.14, 0.8.10 | MIT OR Apache-2.0 |
+| [rustversion](https://crates.io/crates/rustversion/1.0.22), [serde](https://crates.io/crates/serde/1.0.229), [serde_core](https://crates.io/crates/serde_core/1.0.229), [serde_derive](https://crates.io/crates/serde_derive/1.0.229) | 1.0.22, 1.0.229 | MIT OR Apache-2.0 |
+| [serde_json](https://crates.io/crates/serde_json/1.0.151), [shlex](https://crates.io/crates/shlex/1.3.0), [syn](https://crates.io/crates/syn/2.0.117), [syn](https://crates.io/crates/syn/3.0.3) | 1.0.151, 1.3.0, 2.0.117, 3.0.3 | MIT OR Apache-2.0 |
+| [unicode-ident](https://crates.io/crates/unicode-ident/1.0.24) | 1.0.24 | (MIT OR Apache-2.0) AND Unicode-3.0 |
+| [wasm-bindgen](https://crates.io/crates/wasm-bindgen/0.2.114), [wasm-bindgen-macro](https://crates.io/crates/wasm-bindgen-macro/0.2.114), [wasm-bindgen-macro-support](https://crates.io/crates/wasm-bindgen-macro-support/0.2.114), [wasm-bindgen-shared](https://crates.io/crates/wasm-bindgen-shared/0.2.114) | 0.2.114 | MIT OR Apache-2.0 |
+| [windows-core](https://crates.io/crates/windows-core/0.62.2), [windows-implement](https://crates.io/crates/windows-implement/0.60.2), [windows-interface](https://crates.io/crates/windows-interface/0.59.3) | 0.62.2, 0.60.2, 0.59.3 | MIT OR Apache-2.0 |
+| [windows-link](https://crates.io/crates/windows-link/0.2.1), [windows-result](https://crates.io/crates/windows-result/0.4.1), [windows-strings](https://crates.io/crates/windows-strings/0.5.1) | 0.2.1, 0.4.1, 0.5.1 | MIT OR Apache-2.0 |
+| [zmij](https://crates.io/crates/zmij/1.0.23) | 1.0.23 | MIT |
+
+Relevant copyright holders identified by those source distributions include
+Andrew Gallant, Nicolas Silva, Josh Stone, Nick Fitzgerald, Alex Crichton,
+Andrew D. Straw, Nicholas Allegra, the Mozilla Foundation, the Rust Project
+Developers, Microsoft Corporation, and the packages' other authors and
+contributors.
+
+For packages offered under a choice of MIT or Apache-2.0, this distribution
+relies on the MIT option. The MIT notice is reproduced below. MPL-2.0 packages
+are covered by the complete MPL-2.0 text in `LICENSE`; their exact source code
+is available through the versioned links above.
+
+## MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Unicode License v3
+
+Copyright © 1991-2023 Unicode, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+data files and any associated documentation (the "Data Files") or software and
+any associated documentation (the "Software") to deal in the Data Files or
+Software without restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, and/or sell copies of the Data Files
+or Software, and to permit persons to whom the Data Files or Software are
+furnished to do so, provided that either (a) this copyright and permission
+notice appear with all copies of the Data Files or Software, or (b) this
+copyright and permission notice appear in associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD
+PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN
+THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL
+DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
+OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA FILES OR
+SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall not be
+used in advertising or otherwise to promote the sale, use or other dealings in
+these Data Files or Software without prior written authorization of the
+copyright holder.