@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/native-packages.md

@@ -0,0 +1,179 @@
+# Native libraries as August packages
+
+Native locks keep a compiler selection for each host under `native.compilers`.
+A project can record macOS ARM64 and both GNU/Linux hosts without one build
+replacing another host's compiler or runtime pin. A frozen build requires the
+entry for its current host. Run `aug build --backend llvm` once on each new host
+before using `--frozen` there; cross-compilation is not supported.
+
+The LLVM preview lets an August package wrap a C ABI without exposing native
+pointers to application code. A package supplies August declarations, a checked
+binding descriptor, and prebuilt libraries. The compiler checks their labels,
+types, errors, and ownership before generating LLVM IR and a native executable.
+
+This is development work for `0.21.0`, not a capability of the published
+`0.20.1` CLI. Public release installation is being qualified. The first target is
+macOS 14 or later on Apple Silicon. LLVM is the default for ordinary projects
+and native packages. The C migration reference requires `--backend c` or
+`backend: c` in `main.yaml`; native ABI packages require LLVM.
+
+Linux x86-64 and ARM64 support is being qualified on Debian 12 and Ubuntu,
+with glibc 2.36 or later. Both architectures pass LLVM regression and installed
+CLI checks with measured library candidates. Their library artifacts are public;
+clean public-download consumer checks have passed independently on both architectures.
+Compiler publication remains a release gate.
+Musl and cross compilation are unsupported. A package declares its libc floor
+and C++ ABI in addition to its OS and architecture; August rejects an incompatible
+host before compiling the application.
+
+## Import a library
+
+The [PyTorch](https://github.com/GreenPandaStudios/aug-pytorch),
+[SQLite](https://github.com/GreenPandaStudios/aug-sqlite),
+[zlib](https://github.com/GreenPandaStudios/aug-zlib), and
+[BLAKE3](https://github.com/GreenPandaStudios/aug-blake3) repositories publish
+source and native preview archives for all three platforms: PyTorch `v0.1.4` and
+the other three packages `v0.1.3`. Their imports have passed using the packaged CLI,
+public downloads, and fresh caches on macOS ARM64 and both GNU/Linux architectures.
+The matching compiler release is still pending. The consumer gates passed in CI;
+subsequent compiler revisions must pass it again before publication.
+
+After the matching compiler preview is published, use the normal
+package commands. This example adds CPU LibTorch under a short name:
+
+```sh
+aug add https://github.com/GreenPandaStudios/aug-pytorch#v0.1.4 --as pytorch
+aug run
+```
+
+The following program is an example for that preview:
+
+```text
+import Tensor and TensorError and tensor and add and sum from pytorch
+
+try:
+    own Tensor left = tensor(values=[1.0, 2.0, 3.0])
+    own Tensor right = tensor(values=[4.0, 5.0, 6.0])
+    own Tensor result = add(left, right)
+    print(value=sum(tensor=result)) // 21
+catch TensorError error:
+    print(value=error.message)
+```
+
+`own` makes each tensor's lifetime explicit. Leaving its scope releases the
+native tensor, including when a call fails. Reading a tensor lends it for the
+duration of the call. Passing it to an owned input transfers responsibility to
+the callee. Replacing an owned field releases its previous value immediately.
+
+SQLite, zlib, and Rust BLAKE3 use the same package path. The
+[package examples](native-package-examples.md) show their operations; the
+[implementation record](native-implementation.md) separates verified behavior
+from release and platform work still in progress.
+
+Read the complete projects with their compiled explanations:
+[PyTorch](examples/native-pytorch/index.md),
+[SQLite](examples/native-sqlite/index.md),
+[zlib](examples/native-zlib/index.md), and
+[Rust BLAKE3](examples/native-blake3/index.md). Each includes a same-file test and
+a downloadable project. Native dependency pages link to the exact binding
+descriptor, so ownership and native boundaries stay visible beside the code.
+
+## Check and generate bindings
+
+Binding maintainers can use the preview's `aug bind header` command. Supply a
+reviewed `native.abi.json` ownership contract and the adapter's C header. The
+command uses your explicitly selected Clang; it does not install a toolchain or
+run a package recipe.
+
+```sh
+aug bind header native/include/aug_zlib.h \
+  --contract native.abi.json \
+  --target aarch64-apple-darwin \
+  --clang /path/to/pinned/clang \
+  --output .aug-build/checked-bindings
+```
+
+For GNU/Linux, select `x86_64-unknown-linux-gnu` or
+`aarch64-unknown-linux-gnu` in the corresponding maintainer environment. Extra
+Clang include, macro and sysroot flags follow `--`. Consumers still need no
+Clang. Keep the maintainer compiler version pinned in your build recipe.
+
+The command checks physical function types, fixed-width integers, byte booleans,
+buffer lengths, output pointers, release signatures and the ABI error record's
+size, alignment and field offsets. It rejects unsigned results declared as
+August signed integers. Resource input pointers must match their release
+function, and mutable loans cannot use const pointers. It writes generated
+`src` declarations, the descriptor and `header-check.json` only after every
+check passes. Existing output directories are preserved.
+
+Review the generated imports and declarations, then copy them into the package
+beside its handwritten error types and safe API. The command does not invent an
+error class or public wrapper. Include the checked report in native build
+provenance and repeat the check whenever headers, compiler flags or descriptors
+change. The report records compiler, target, header digests and signatures.
+
+Ownership, allocator pairing, retention and thread behavior remain promises
+made by the binding author. A matching header cannot establish those promises;
+independent adapter tests must check them. C++ and Rust packages provide C
+adapter headers for this command. Templates, callbacks, variadic calls and
+aggregate values are outside the initial binding profile.
+
+## Installation and deployment
+
+`aug.lock.json` records the source revision, binding digest, selected native
+archive, compiler pack, and runtime identity. Archive downloads are bounded and
+SHA-256 checked. Extraction rejects links, traversal, duplicate paths, and
+unexpected files. Cached files are checked again before use. Package installation
+does not execute native recipes or npm lifecycle scripts.
+
+A failed download or extraction leaves no accepted artifact cache. Disk-full
+errors include the CLI's space-recovery guidance; they do not leave a partially
+installed library selected by a lockfile.
+
+Consumers need Node 24 and a supported OS, but do not install LLVM or Clang for
+this profile. August downloads its own pinned LLVM tools and runtime. A missing
+or incompatible artifact produces a diagnostic; it never starts a source build.
+Use `aug run --offline --frozen` after an online installation to require the
+recorded artifacts without downloading replacements.
+
+Public GitHub source downloads use HTTPS and do not require Git. If GitHub's
+shared API rate limit stops installation, retry later or set `AUG_GITHUB_TOKEN`
+to authenticate API reads. August sends this token only to `api.github.com`,
+rejects redirects, and never writes it to source caches or lockfiles.
+
+Keep the executable together with its adjacent `lib` and `share` directories.
+The libraries load relative to the executable. `share/august-native` preserves
+the selected packages' notices, provenance, and file manifests.
+
+## Author a binding
+
+Declare an opaque resource with `extern C resource Handle` in an ordinary module.
+Hover, `aug context` and the compiled specification show the native provider,
+supported targets, loan duration and release operation. The compiler checks the
+binding signature and ownership at August call sites. Input retention, thread
+behavior and exception containment are promises made by the native author; these
+tools do not prove the foreign implementation follows them. Context identifies
+native dependencies reached through resolved standalone calls and does not claim
+complete member-dispatch coverage.
+Its `native.abi.json` entry names a leaf release function. Extern declarations
+and descriptor entries must agree; application code imports safe August wrappers
+through `export.aug`. Calls to extern functions remain inside `unsafe`.
+
+The initial ABI uses fixed-width scalars, pointer-and-length inputs, copied
+buffers, opaque handles, and checked status errors. C++ wrappers catch exceptions
+and Rust exports contain panics before returning through C. Sharing LLVM does
+not make C++, Rust, and August layouts compatible.
+
+Binding maintainers build and test native artifacts with the recorded toolchain.
+Consumers receive those verified artifacts. Callback registration, retained
+loans, foreign threads, native struct layout, GPU tensors, and exporting August
+libraries have not been qualified. See the
+[architecture and backlog](native-interop-llvm-plan.md).
+
+Linux maintainers build on Debian 12 so newer hosts do not raise the artifact's
+glibc requirement. The compiler checks the declared minimum; maintainer builds
+inspect each binary's actual symbol-version requirements and dependency closure.
+C++ adapters keep their qualified C++ runtime with the artifact. Source builds
+use Clang, platform headers and Linux relocation tools explicitly, while Rust
+adapters also use their pinned Rust/Cargo toolchain. Consumer installation has
+no automatic source-build fallback.

package/docs/packages.md

@@ -1,184 +1,130 @@
 # Packages and installation
 
-The [augscript monorepo](https://github.com/GreenPandaStudios/augscript) versions the compiler, libraries, documentation, and editor together. Release packages contain the files needed to use them; they do not run install scripts or silently build native libraries.
+August libraries are source folders with an `export.aug` file. An application imports their public declarations, and the compiler checks those declarations with the application. A library can live in a public Git repository, a local folder, or an npm archive.
 
-| Distribution | Package | Provides |
-| --- | --- | --- |
-| CLI | `@greenpandastudios/aug-cli` | `aug`, `aug-cli`, `aug-native`, compiler, language server, C runtime, guides and examples |
-| Standard library | `@greenpandastudios/aug-stdlib` | `august.io`, `august.json`, `august.time`, `august.memory` |
-| Web library | `@greenpandastudios/aug-web` | `august.web`, HTTP capabilities and helpers |
-| Crypto library | `@greenpandastudios/aug-crypto` | `august.crypto`, cryptographic capability, RSA JWK and signed JWT helpers |
-| VS Code | `augscript.augscript` / `.vsix` | Syntax, file icons, hover, completion, fixes, navigation, tests and bundled compiler |
-
-## From a checkout
+## npm registry
 
-Requires Node.js 24+, npm, and a C11 compiler. Full web/crypto native builds run on macOS and Linux; the repository's Docker recipes supply the Linux build tools and libraries. Other platforms remain outside the tested support matrix.
+Install the CLI once:
 
 ```sh
-git clone git@github.com:GreenPandaStudios/augscript.git
-cd augscript
-npm ci
-node scripts/bootstrap-native.mjs --extract-only --only minicoro,yyjson
-node bin/aug.mjs run examples/approved-design
-node scripts/bootstrap-native.mjs
-node bin/aug.mjs run examples/oidc-login
+npm install --global @greenpandastudios/aug-cli@next
+aug init hello-august
+cd hello-august
+aug run
 ```
 
-## Install release tarballs
+The pending 0.21.0 release needs Node.js 24 or later and npm on macOS 14+ ARM64 or GNU/Linux x64/ARM64 with glibc 2.36+. August downloads a verified LLVM/runtime pack; native package consumers do not install a compiler or SDK. GitHub repository imports use the CLI's HTTPS transport without Git. Other Git servers require a local Git client. [Docker](docker.md) and [Dev Containers](dev-containers.md) provide a Linux workspace. The published 0.20.1 CLI still requires a C11 compiler.
+
+`aug run` finds `main.aug`, installs source dependencies declared by imports or `main.yaml`, checks the code, prepares the native libraries it needs, and compiles and starts the executable. Later runs reuse those dependencies. `aug check` and `aug spec` read the installed snapshot without fetching packages. Use `aug install` before those commands in a fresh project.
 
-Until registry publication is configured, download all four `.tgz` files from the same [GitHub release](https://github.com/GreenPandaStudios/augscript/releases). Install them together, replacing VERSION with the release version:
+To use npx instead of a global installation:
 
 ```sh
-npm install --global ./greenpandastudios-aug-stdlib-VERSION.tgz ./greenpandastudios-aug-web-VERSION.tgz ./greenpandastudios-aug-crypto-VERSION.tgz ./greenpandastudios-aug-cli-VERSION.tgz
-aug --version
-aug --help
-aug-native
-aug check path/to/project
-aug run path/to/project
+npx @greenpandastudios/aug-cli@next init another-app
+cd another-app
+npx @greenpandastudios/aug-cli@next run
 ```
 
-The CLI depends on exact matching library versions. Import spellings stay `import Crypto from august.crypto`; npm package names never enter August source. The packaged CLI loads the separate installed libraries, and editor navigation opens their real `.aug` files.
-
-Native dependencies use `~/.cache/augscript/native/VERSION/PLATFORM-ARCH` for an installed CLI. Source checkouts use `.aug-native`. `AUG_NATIVE_HOME` selects a shared cache for CLI and VS Code; building dependencies is an explicit command.
+Both starters include `AGENTS.md`, which tells coding agents to read neighboring compiled specs, keep tests beside declarations, and check their changes. For a service, [start the weather API](weather-api.md) with `init weather --template weather`.
 
-For core programs and JSON without web/crypto, `aug-native --extract-only --only minicoro,yyjson` downloads just the portable C sources. Compiler checkpoints use minicoro even in ordinary programs; this source dependency must be present before native execution. Full web/crypto bootstrap is available on macOS and Linux.
+August is a preview. Pin an exact CLI release for a repeatable toolchain. The source-package and weather workflows on this page require the ecosystem release; 0.19.0 predates them. [GitHub releases](https://github.com/GreenPandaStudios/augscript/releases) list the available compiler and extension versions.
 
-## npm registry
+## Use a package
 
-Create a project with the published CLI:
+Give a public repository a short name:
 
 ```sh
-npx @greenpandastudios/aug-cli@next init hello-august
+aug add https://github.com/GreenPandaStudios/augscript/src/stdlib/json --as json
 ```
 
-`aug init DIRECTORY` creates a checked application with `main.aug`, a public interface and implementation, a same-file test, README, and `.gitignore`. It refuses a nonempty directory. The npm package exposes `aug-cli` as a binary so `npx` can select the executable by package name. The CLI brings its three matching libraries. Early releases use the `next` dist tag. **This npm package has not been published yet**, so use the checkout or release tarballs above until the owner configures npm access. Registry and Marketplace publication require their own owner accounts; a GitHub account does not grant those identities. See [releasing](releasing.md) for configuration and [getting started](getting-started.md) for the starter command.
+This installs the source and writes its URL under the `json` alias in the `packages` block of `main.yaml`. A source fragment using the alias is:
 
-## VS Code
+```text
+import parse from json
+```
 
-Install **AugScript** (`augscript.augscript`) from the VS Code Extensions view once its [Marketplace listing](https://marketplace.visualstudio.com/items?itemName=augscript.augscript) is published. The listing is currently unpublished pending owner identity setup. Release publication runs the Marketplace workflow described in [releasing](releasing.md).
+You can also put the repository URL directly in an import. This fragment declares its own dependency:
 
-For direct installation, download the matching `.vsix` from [GitHub Releases](https://github.com/GreenPandaStudios/augscript/releases) and choose **Extensions → Install from VSIX**.
+```text
+import parse from "https://github.com/GreenPandaStudios/augscript/src/stdlib/json"
+```
+
+Run the application to install it. GitHub URLs can select a folder inside a repository. Append `#v1.2.3` to choose a release tag, or `#COMMIT` to choose a commit. Without a revision, the first installation selects the repository's current default branch. `aug.lock.json` records the exact commit either way.
 
-The extension bundles the same compiler sources, standard declarations, native bootstrap, guides, and examples. Set `augscript.nativeHome` to an existing dependency build directory. Node.js 24+ remains required.
+Imported names must appear in that folder's `export.aug`. An exported child folder has its own export file. A dependency's private names and unexported files remain inaccessible.
 
-## Package model
+## Official libraries
 
-`packages/*/package.json` and `aug-package.json` are release manifests. Canonical code lives in `src`, `runtime`, and `src/stdlib`; generated staging directories live under ignored `dist`. `npm run package:packages` builds JavaScript and real npm tarballs. `npm run test:packages` installs those tarballs outside the checkout and checks imports, navigation, native execution, and compatibility.
+The compiler supplies `august.io` for console, file, and argument capabilities. JSON, time, in-memory stores, web helpers, and cryptography are optional source packages. Add only what your application uses:
 
-User packages ship August source, retain their own public boundaries, and compile into the application's native executable. They use npm for archive/registry transport and August for visibility, compatibility, dependency scopes and checking. Changing builtin libraries independently of the compiler is unsupported; general native adapter ABI/version distribution remains future work.
+| Alias | Repository folder | API |
+| --- | --- | --- |
+| `json` | `src/stdlib/json` | [Parse JSON](api/json.md) |
+| `time` | `src/stdlib/time` | [Read a clock](api/time.md) |
+| `memory` | `src/stdlib/memory` | [Bounded expiring stores](api/memory.md) |
+| `web` | `src/stdlib/web` | [HTTP client and server helpers](api/web.md) |
+| `crypto` | `src/stdlib/crypto` | [Crypto and signed tokens](api/crypto.md) |
 
-With the full native bootstrap ready, `npm run test:packages -- --native` additionally builds the OIDC example and runs its signed-identity tests using the installed CLI and separate packages.
+Each folder is under `https://github.com/GreenPandaStudios/augscript/`. For example, use `aug add https://github.com/GreenPandaStudios/augscript/src/stdlib/web --as web`. Endpoints, records, headers, and server-rendered HTML are language features; a simple weather service needs none of these optional packages.
 
 ## Author a package
 
-Create a standalone library; it needs no `main.aug`:
+Create a library:
 
 ```sh
-aug package init my-math --name @your-npm-name/aug-math
-aug check my-math
-aug test my-math
-aug package pack my-math
+aug package init arithmetic
+cd arithmetic
+aug check
+aug test
+aug spec
 ```
 
-The scaffold includes `src/arithmetic.aug` with a same-file test, `src/export.aug`, `aug-package.json`, and npm's `package.json`. Public API, Javadoc and tests stay beside the implementation:
+The starter exports `add` from `src/arithmetic.aug`, keeps its test in that file, and includes agent instructions. Edit `src/export.aug` to choose the public surface. A library needs no `main.aug` and does not start an application when imported.
 
-```text
-// src/arithmetic.aug
-/** Add two integers. @param left First integer. @param right Second integer. */
-add(int left, int right) returns int:
-    return left + right
-
-test add:
-    when addition:
-        it adds:
-            assert(add(left=2, right=3) == 5)
-
-// src/export.aug
-export add from arithmetic
-```
+For a library you write by hand, `export.aug` in the root or a `src` folder is enough. `aug-package.json` is optional; use it when you want to name a package, state its version and compiler, choose another source folder, or declare dependency aliases. npm metadata is only needed for npm distribution.
 
-`aug-package.json` owns August metadata and dependency aliases:
-
-```json
-{
-  "format": 1,
-  "name": "@your-npm-name/aug-math",
-  "version": "0.1.0",
-  "compiler": "0.19.0",
-  "source": "src",
-  "dependencies": {}
-}
-```
-
-`package.json` supplies npm transport metadata, description, license, README and the files to include. `aug install` and `aug package pack` synchronize its name, version and dependencies from the August manifest. Keep the source folder and `aug-package.json` in its `files` list. Pack checks every declaration and test closure before creating `.aug-build/packages/your-npm-name-aug-math-0.1.0.tgz`. It checks test code; execute the cases with `aug test` before release.
-
-After authenticating with an npm account that owns the namespace, publish that verified archive:
-
-```sh
-npm publish my-math/.aug-build/packages/your-npm-name-aug-math-0.1.0.tgz --access public
-```
+Put the source in your own Git repository and publish a release tag. Other projects can then import your repository URL with `#v0.1.0`. Commit the source, export file, tests, comments, and dependency lock. Choose a license and include its notice. Run your checks before publishing a tag; a Git commit fixes the source contents, not their quality or permission to redistribute them.
 
-This is an explicit author action; `aug install` never publishes or executes dependency lifecycle scripts. August does not require a new registry account in addition to npm. See [npm's package publishing guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
+## Dependencies between libraries
 
-## Use a package
+A library can import another repository URL directly. The installer follows those imports and installs the complete graph. Each library has its own aliases and export boundaries; its dependencies do not become imports in the application automatically.
 
-In the consuming application's `main.yaml`, choose a readable import alias:
+For local development, use an alias mapped to a folder:
 
 ```yaml
 packages:
-  math: "npm:@your-npm-name/aug-math@0.1.0"
+  arithmetic: ../arithmetic
 ```
 
-Install explicitly, then import the public name:
-
-```sh
-aug install my-app
-aug run my-app
-```
-
-```text
-// my-app/main.aug
-import add from math
-print(value=add(left=20, right=22))
-```
-
-Local development uses the same source syntax. Replace the specification with `"../my-math"`, `"file:../my-math"`, or a path to the `.tgz`. `aug install` snapshots a local directory, so reinstall after editing its source. Check and build never fetch dependencies or silently refresh a local package. There are no symlinked live dependencies.
-
-Only the source root's `export.aug` is visible to another package. To expose a submodule, write `export folder parsing` there and provide `src/parsing/export.aug`; consumers can then use `import Parser from math.parsing`. Private `_names`, files and folders remain inaccessible. `import everything` follows the same public surface. An alias cannot shadow a local file/folder or use the reserved `august` name.
+Then run `aug install`. Local dependencies inside a library resolve relative to that library's original folder. To share the library remotely, replace development paths with public repository URLs or exact registry versions.
 
-Module dependency policies use the alias path (`math` or `math/parsing`) for external edges. Consumer architecture/style lints apply to its own source; they do not impose its conventions on library internals.
-
-Ctrl-click an imported declaration, `from`, or a path segment to open the installed source or its export file. Hover preserves its Javadoc. VS Code recognizes a standalone library from `aug-package.json` and refreshes when the manifest or lock changes.
-
-## Dependencies between libraries
+## Reproducible builds
 
-Declare dependencies in the library's August manifest instead of `main.yaml`:
+Commit `aug.lock.json`. It records repository commits, registry archive integrity, source hashes, and the dependency graph. Installed sources live in `.aug-packages`; do not edit or commit that directory.
 
-```json
-"dependencies": {
-  "math": "npm:@your-npm-name/aug-math@0.1.0"
-}
+```sh
+aug install --frozen
+aug check
+aug test
+aug build
 ```
 
-Run `aug install` inside that library and use `import add from math`. Each package sees its own declared aliases. A consuming app cannot import a transitive alias unless it also declares that dependency. Multiple package versions have distinct type identities; duplicate copies of the same version share declarations only when their source and dependencies agree. Changed code with the same package name/version is rejected when conflicting copies would coexist.
+A frozen install restores the recorded revisions and rejects changed source contents. `aug install --update` deliberately selects current revisions again. A normal install preserves a matching lock. `aug run --offline` and `aug install --frozen --offline` use previously cached sources and native dependencies; an uncached input produces an error explaining how to prepare it online.
 
-Registry dependencies require exact versions. Ranges, latest tags, Git dependencies and arbitrary URLs are unsupported. Local paths are useful within a development workspace; publish registry references for libraries other developers will install.
+Git packages are read as source blobs without a checkout or hooks. Registry archives are checked and extracted without lifecycle scripts. These precautions protect installation; review a library before running an application that uses it, especially native adapters and unsafe operations.
 
-## Reproducible builds
+## npm archives and releases
 
-Commit `aug.lock.json` with your project. It records specifications, the installed graph, exact names/versions, npm integrity metadata, the compiler version, and hashes of source/manifests. `.aug-packages` is an ignored installed snapshot.
+For npm distribution, use `aug package init arithmetic --name @owner/arithmetic`, then `aug package pack`. Packing checks the library and its test bodies, generates specs, synchronizes npm metadata, and prints the archive path. Run `aug test` yourself before publishing the archive with npm.
 
-```sh
-aug install my-app --frozen
-aug check my-app
-aug test my-app
-aug build my-app
-```
+Consumers can use `aug add npm:@owner/arithmetic@0.1.0 --as arithmetic` or a local `.tgz` path. Registry versions must be exact. Git, registry, and local dependencies can appear in the same graph.
 
-`--frozen` requires a matching lock and unchanged source graph. `--offline` additionally prohibits fetching uncached dependencies; a fresh machine may need one online install before it can work offline. Editing the installed source produces a diagnostic requiring a reinstall. The compiler version must match exactly while the language is experimental.
+## VS Code
 
-Libraries support `check`, same-file `test`, formatting, explain, editor help, and packing. `run`, `build`, `bench` and server OpenAPI generation belong to an application with `main.aug`. Consumer tests run the consumer's suites; dependency tests are checked and executed by the package author. Arbitrary C source, native build hooks, precompiled August binaries, compiler plugins and stable native ABIs are outside this package format.
+Install [AugScript](https://marketplace.visualstudio.com/items?itemName=augscript.augscript), or install the matching `.vsix` from [GitHub releases](https://github.com/GreenPandaStudios/augscript/releases). The extension bundles a compiler and uses the project's installed source graph for completion, help, and navigation. [Editor guide](editor.md) explains call completion, fixes, and contract hints.
+
+## Install release tarballs
 
-`aug spec` also works on source libraries. `aug pack DIRECTORY` is an alias for `aug package pack DIRECTORY`. Packing refreshes and includes adjacent `.aug.md` files and `.aug-spec/` so the package carries complete source explanations and precise-version offline dependency links. See [compiled specifications](specifications.md).
+The CLI tarball requires its matching core stdlib package. npm normally obtains it automatically. For an archive installation, install the matching CLI and stdlib tarballs together; optional web and crypto packages are regular source libraries.
 
-The [package example](../examples/packages/README.md) exercises the author and consumer workflow locally. The installer uses [npm aliases](https://docs.npmjs.com/cli/v11/using-npm/package-spec/) and [npm install](https://docs.npmjs.com/cli/v11/commands/npm-install/) with lifecycle scripts disabled and local packages installed as copied archives.
+Verified LLVM packs and native artifacts use `~/.cache/augscript/native-artifacts`, keyed by their archive hashes. `AUG_NATIVE_ARTIFACT_CACHE` selects another cache. Source, compiler, runtime, and platform selections remain in `aug.lock.json`. The C migration reference uses the older `AUG_NATIVE_HOME` source-build cache. The [native package guide](native-packages.md) covers ownership, platform requirements, and publishing; [release process](releasing.md) covers the compiler distribution.