@greenpandastudios/aug-cli 0.19.0 → 0.20.1

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
+You need Node.js 24 or later, npm, and a C11 compiler. Repository packages also need Git. macOS and Linux are the tested platforms. [Docker](docker.md) and [Dev Containers](dev-containers.md) provide a Linux toolchain when you prefer to work in a container.
+
+`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.
+Native dependencies use `~/.cache/augscript/native/VERSION/PLATFORM-ARCH`. `AUG_NATIVE_HOME` selects another cache. `aug-native` can prepare a cache in advance; `aug run` prepares what the application needs. The [release process](releasing.md) documents toolchain publishing for contributors.

package/docs/performance.md

@@ -1,6 +1,8 @@
 # Performance and benchmarks
 
-Use this page to measure an August application, read the comparison graphs, and inspect the exact August programs behind each result. The recorded results used August 0.18.0, which compiles to native code through C. The current compiler is 0.19.0; rerun the suite before comparing a new release. Always measure work that resembles your application.
+This page publishes measurements for specific August programs alongside C, Node, and Python versions. Read the graphs for a quick comparison, inspect each program below, and use the reproduction commands to measure work that resembles your application.
+
+The recorded suite used August 0.18.0 and native C output. The current compiler is 0.20.1; these graphs have not been remeasured for that release. A result for one workload and host does not establish a general speed advantage or production readiness. [Readiness](production-readiness.md) covers reliability and deployment evidence separately.
 
 ## Read the graphs
 
@@ -115,7 +117,7 @@ record Payload(int id, string message, List<int> values)
 **main.aug**
 
 ```aug project=benchmark-json file=main.aug
-import parse from august.json
+import parse from "https://github.com/GreenPandaStudios/augscript/src/stdlib/json#v0.19.0"
 import Payload from data
 int checksum = 0
 int index = 0
@@ -181,10 +183,10 @@ serve reply on port 0
 Start the app in one terminal:
 
 ```sh
-aug run path/to/http-example
+npx @greenpandastudios/aug-cli@next run path/to/http-example
 ```
 
-Save the load generator below as `http-load.mjs`, or use `scripts/http-load.mjs` from a repository checkout. In another terminal, replace `PORT` with the printed port. This is the **same load generator** the comparison suite uses:
+Save the load generator below as `http-load.mjs`. In another terminal, replace `PORT` with the printed port. This is the **same load generator** the comparison suite uses:
 
 ```sh
 node http-load.mjs --url http://127.0.0.1:PORT/bench \
@@ -322,50 +324,20 @@ The same August programs and measurement settings were run on this machine befor
 3. Measure a release executable repeatedly. Compilation is excluded; process startup is included.
 
 ```sh
-aug check path/to/project
-aug run path/to/project
-aug bench path/to/project --iterations 20 --warmup 3 --json > benchmark.json
+npx @greenpandastudios/aug-cli@next check path/to/project
+npx @greenpandastudios/aug-cli@next run path/to/project
+npx @greenpandastudios/aug-cli@next bench path/to/project --iterations 20 --warmup 3 --json > benchmark.json
 ```
 
 `aug bench` compiles with release optimization even when the project's normal setting is debug. Do not benchmark `aug run`: that command includes compiler work. Server programs run indefinitely, so use an HTTP load generator against a built server instead of `aug bench`. Record errors and latency as well as throughput. The comparison suite validates checksums; `aug bench` itself checks exit status, so verify your program's result first.
 
-## Reproduce the comparison graphs
-
-From a checkout, with Node 24+, Python and a C11 compiler:
-
-```sh
-npm ci
-node scripts/bootstrap-native.mjs
-npm run bench:compare
-```
-
-Set `AUG_BENCH_PYTHON=/path/to/python3` or `CC=/path/to/clang` to select the reference interpreter/compiler. `AUG_NATIVE_HOME` selects the native dependency cache. The raw result file records versions and a source fingerprint. Compilation timings are included separately from executable run time.
-
-For core/JSON only, extract the smaller native source dependencies and omit HTTP:
-
-```sh
-node scripts/bootstrap-native.mjs --extract-only --only minicoro,yyjson
-npm run bench:compare -- --skip-http
-```
-
-The full suite writes `docs/benchmark-results.json`; a core-only run writes `.aug-build/benchmarks/results-core.json` and preserves the complete wiki measurements. Focus on selected workloads while trying your own changes:
-
-```sh
-npm run bench:compare -- --only cpu,collections-200k
-npm run bench:compare -- --only http --http-requests 10000
-```
+## Reproduce the programs
 
-Focused runs write `.aug-build/benchmarks/results-focused.json`. Use `--output PATH` to keep separate reports. Render graphs, tables and the exact source examples from the full result file using Python 3.12+:
+Download a [measured project](examples/index.md#measured-programs), extract it, and prepare [native dependencies](packages.md#npm-registry). Each download contains the code and configuration shown in the gallery. Run finite programs with the commands under [Benchmark your own project](#benchmark-your-own-project); use [the HTTP load generator](#http-program) for the server. The complete C, Node, and Python reference programs are below, so you can save and inspect the comparison code too.
 
-```sh
-python3 -m venv .aug-build/benchmark-plotting
-.aug-build/benchmark-plotting/bin/python -m pip install -r benchmarks/plot-requirements.txt
-.aug-build/benchmark-plotting/bin/python scripts/render-benchmarks.py
-.aug-build/benchmark-plotting/bin/python scripts/render-benchmarks.py --check
-npm run docs:build
-```
+The 200,000-entry collection run changes `20000` to `200000` in the downloaded Map/Set program. Keep the matching input count in each reference implementation and verify the published checksum before comparing timings. Record the machine, compiler, toolchain version, input size, and flags with your results.
 
-The plot environment is isolated and ignored; published documentation includes the rendered graphs and needs no Python installation. Review this page's environment, interpretations and limitations when replacing measurements. Short exploratory runs can use `--iterations 3 --warmup 1 --http-rounds 1 --http-requests 1000`; they have less statistical coverage.
+[Maintaining the comparison suite](contributing-benchmarks.md) describes the contributor workflow that produces the full graphs, raw samples, and checked source panels.
 
 ### Comparison implementation sources
 

package/docs/production-readiness.md

@@ -1,10 +1,10 @@
 # Production readiness and dependencies
 
-August 0.19 is experimental. The compiler, CLI, packages, standard declarations, and editor can be tried today; the project does not claim general production readiness. Use the [getting-started guide](getting-started.md) for a first application, [the roadmap](roadmap.md) for release gates, and [the compatibility page](compatibility.md) for the proposed 1.0 support contract.
+August 0.20 is experimental. The compiler, CLI, packages, standard declarations, and editor can be tried today; the project does not claim general production readiness. Use the [getting-started guide](getting-started.md) for a first application, [the roadmap](roadmap.md) for release gates, and [the compatibility page](compatibility.md) for the proposed 1.0 support contract.
 
 ## What is measured and verified
 
-The repository checks compiler types, native execution, language examples, generated specs, package installation outside the checkout, and the VS Code extension in CI. [Performance measurements](performance.md) compare specific programs and HTTP loads on named hardware. A benchmark is evidence for that program and environment, not a general speed guarantee.
+The repository checks compiler types, native execution, language examples, generated specs, package installation in isolated projects, and the VS Code extension in CI. [Performance measurements](performance.md) compare specific programs and HTTP loads on named hardware. A benchmark is evidence for that program and environment, not a general speed guarantee.
 
 The [robustness tests](../tests/robustness.test.mjs) mutate 5,000 source files through the parser and 1,000 through project checking, then compare generated native integer, Map, and Set programs in debug and release modes with independent JavaScript oracles. CI also runs [core native stress programs](../scripts/sanitize-core.mjs) for collections, task joining, and owned `Shared<T>` transfer with AddressSanitizer and UBSan on macOS and Linux. Run them locally with `npm run test:sanitizers`. This catches specific crashes, wrong results, and memory errors in the exercised paths; it does not prove the compiler, HTTP/crypto libraries, or all programs safe. Leak detection is disabled for this gate because the macOS AddressSanitizer runtime does not support it.
 
@@ -12,10 +12,11 @@ The same-app [OpenID Connect example](examples/oidc-login/index.md) proves integ
 
 ## Dependencies and licenses
 
-The npm CLI and three August library packages have **no npm production dependencies outside their matching August packages**. The VS Code extension's npm audit currently reports zero advisories. The wiki build uses VitePress and a pinned Vite override; run `npm audit` before each release. npm audit only covers npm packages and cannot certify native code or deployment configuration.
+The CLI uses its matching core August library and `tar` 7.5.22 for registry archive extraction. The extension bundles that parser and its JavaScript dependencies. The VS Code extension's npm audit currently reports zero advisories. The wiki build uses VitePress and a pinned Vite override; run `npm audit` before each release. npm audit only covers npm packages and cannot certify native code or deployment configuration.
 
 | Dependency | Role | License from upstream | Distribution consideration |
 | --- | --- | --- | --- |
+| tar, chownr, yallist, minipass, minizlib, @isaacs/fs-minipass | Archive extraction in the CLI and extension | ISC, MIT, or BlueOak-1.0.0, as recorded in each package | Preserve the bundled license files and review npm audit before release. |
 | minicoro | Portable task runtime source | Public domain or MIT No Attribution | Source is fetched with a checked SHA-256. |
 | yyjson | JSON source | MIT | Source is fetched with a checked SHA-256. |
 | libwebsockets | Native HTTP library | MIT core; bundled portions have their own notices | Static link in a full native build; preserve applicable notices. |
@@ -33,7 +34,7 @@ The exact versions, archive URLs, and SHA-256 values are in [`native-dependencie
 - **Platform support:** the full pinned web/crypto bootstrap passes on macOS ARM and Linux ARM. [Docker build/run bases](docker.md) run core, web, and crypto programs on Linux. Linux x86-64 runs in CI; other platforms remain unverified.
 - **Concurrency and ownership:** tasks use one OS thread. The [conformance suite](language-conformance.md) exercises injected captures, mutation after a child starts inside `borrow`, owned `Shared<T>` cleanup, branch joins, cancellation, and the public `Task<T>` error contract. A 1.0 support claim still depends on the platform, distribution, and compatibility gates.
 - **Security and reliability:** HTTP and OIDC need broad protocol conformance, durable credentials and keys, rotation, long-running load tests, and deployment guidance. The [gap ledger](web-library-gaps.md) records the precise work.
-- **Package and ABI stability:** published npm identities, reproducible releases, compatibility policy, and native adapter ABI need stable release gates.
+- **Package and ABI stability:** the [matching 0.19.0 npm packages](packages.md#npm-registry) are published and their core starter workflow is verified. Reproducible releases, compatibility policy, and native adapter ABI still need stable release gates.
 - **Operational behavior:** failure handling, cancellation, instrumentation, platform builds, and resource ceilings need repeated CI and field testing.
 
 For a trial deployment, pin the compiler and native lock, run the project's tests and `aug spec --check`, review the generated C/native linker inputs, and validate the executable under your own load and failure conditions. Track the [gap ledger](web-library-gaps.md) before promising production service levels.

package/docs/reference.md

@@ -1,6 +1,8 @@
-# AugScript language guide
+# Language reference
 
-Version 0.18. The language aims for code that communicates behavior, dependencies, and effects to a developer seeing a module for the first time.
+Use this page to look up the implemented language rules. It covers syntax, types, visibility, effects, dependency injection, ownership, and checked failures. For a first introduction, read [the August book](learn/index.md). For the reasons behind the design, read [why August exists](about.md).
+
+The reference is maintained with the compiler in this repository. August is experimental; [compatibility](compatibility.md) describes its version policy. Examples marked with a project and filename form complete applications and are checked by the documentation tests. Short `text` blocks illustrate syntax and are not standalone projects.
 
 ## A complete project
 
@@ -30,7 +32,7 @@ Application(resolve Console console) implements Runnable:
         console.write(value="Hello, AugScript!")
 ```
 
-Run `node bin/aug.mjs run PROJECT`, or choose **AugScript: Run Project** in VS Code. Node.js 24+ and a C11 compiler are required.
+Run `npx @greenpandastudios/aug-cli@next run PROJECT`, or choose **AugScript: Run Project** in VS Code. Node.js 24+ and a C11 compiler are required; prepare [native dependencies](packages.md#npm-registry) before execution.
 
 ## Blocks and statement boundaries
 
@@ -182,9 +184,9 @@ Empty literals require context: `List<int> values = []`, `Set<int> values = {}`,
 
 | Type | Reading | Mutation |
 | --- | --- | --- |
-| List | `length()`, `get(index=...)` unless IndexError, `at(index=...)` returns T? | `append(value=...)` |
+| List | `length()`, `get(index=...)` unless IndexError, `at(index=...)` returns `optional T` | `append(value=...)` |
 | Set | `length()`, `contains(value=...)` | `add(value=...)` |
-| Map | `length()`, `contains(key=...)`, `get(key=...)` returns V? | `set(key=..., value=...)` |
+| Map | `length()`, `contains(key=...)`, `get(key=...)` returns `optional V` | `set(key=..., value=...)` |
 | Tuple | `length()`, `get(index=constant)` with compile-time bounds | None |
 
 Managed mutations need a borrow; owned collections mutate directly. Collections cannot store borrowed or owned references by copying them. Reference results grant reading.
@@ -193,9 +195,9 @@ Tuple destructuring introduces new local names and checks arity. `for item in va
 
 ## Functions, effects, and capabilities
 
-A bare header without `implements` declares a function. Omitting `returns` means void. Non-void bodies must return or throw on every path. A bodyless top-level declaration cannot be called unless it is an extern declaration.
+A bare header without `implements` declares a function. A body infers its result from return expressions or an implemented interface. A body with no returned value has a void result; a bodyless signature needs `returns T` for a non-void result. Non-void bodies must return or throw on every path. A bodyless top-level declaration cannot be called unless it is an extern declaration.
 
-Public standalone functions and interface contracts are pure unless they declare capabilities. State transitions declare `changes self` or `changes input`; mutable reference inputs require `borrow` or `own`. A helper cannot mutate a managed input, an alias, or nested objects reachable through it.
+Bodies infer capability use and state transitions. Bodyless interfaces declare permitted `uses` and `changes`; mutable reference inputs require `borrow` or `own`. A helper cannot mutate a managed input, an alias, or nested objects reachable through it.
 
 I/O uses capability interfaces and checked `uses dependency.operation` contracts. Capability types have interface behavior and permit explicit adapter substitution. The standard `august.io` folder provides Console/SystemConsole, FileReader/FileWriter/LocalFiles, and Arguments/ProcessArguments.
 
@@ -210,7 +212,7 @@ announce(message="Dependencies are visible")
 ```aug project=capabilities-guide file=messages.aug
 import Console from august.io
 
-announce(resolve Console console, string message) uses console.write:
+announce(resolve Console console, string message):
     console.write(value=message)
 ```
 
@@ -218,25 +220,29 @@ A caller's contract must include the effects of its calls and interceptor layers
 
 ### Short implementation headers
 
-Class methods and private `_helpers` infer `uses` when it is omitted. Interfaces, public standalone functions, interface default methods, and interceptor `around` methods retain explicit effect contracts. An explicit `uses` clause is an upper bound, including on implementations. `changes` and `unless` are still explicit.
+Executable functions, methods, interface defaults, and interceptors infer omitted `returns`, `changes`, `uses`, and `unless` clauses. You write the work once. Return expressions determine the result; calls and writes determine capabilities and observable mutations; failures that escape catches determine checked errors. Record validation also infers escaping failures.
 
 ```text
-import Console from august.io
+import Console and FileReader from august.io
 
 interface Logger:
     log(string message) uses Console.write
 
 ConsoleLogger(resolve Console console) implements Logger:
     log(string message):
-        _write(console, message)
+        console.write(value=message)
 
-_write(Console console, string message):
-    console.write(value=message)
+load(resolve FileReader files, string path):
+    return files.read(path)
 ```
 
-Both bodies infer `Console.write`; the interface states it once. Inference follows calls, generic substitutions and interceptor layers to a fixed point, so declaration order does not matter. Hover and `aug explain` show inferred capabilities; generated library API pages include them. Calling an inferred helper from a pure public function is a compile error. A pure interface cannot acquire hidden I/O through its implementation.
+The editor shows `uses Console.write` beside `log` and `returns string uses FileReader.read unless FileError` beside `load` as non-editable hints. These clauses are absent from saved code. Hover, `aug explain`, generated API docs, and `aug spec` use the same checked contracts. Formatting keeps concise source; it preserves annotations you wrote deliberately.
+
+Bodyless interfaces and foreign declarations describe contracts the compiler cannot inspect. A written clause remains a checked assertion: `returns void` rejects a returned value, and an explicit `uses` or `unless` limits the body. Implementations must satisfy their interface. An interface with no effects remains pure. Inference follows calls and generic substitutions independently of declaration order. Recursive results without an anchor, empty collections without a contextual type, and expanding generic contracts need an explicit type or finite contract.
+
+`borrow`, `own`, `resolve`, `mutable`, HTTP input sources and error-status mappings express permissions or choices. They stay in source. Inferred mutation cannot grant access to a managed input. Constructors and `drop()` keep their purity rules, and inferred I/O remains forbidden under a lock. A fresh local `Shared` value needs no artificial external-effect clause; retained external shared state still requires its capability or mutation contract. A forwarding interceptor can inherit each target's result; an interceptor that needs a fixed result contract can state it.
 
-Capability implementations inherit their operation contract even when a test adapter does no I/O. This includes shared-state capabilities such as `ExpiringStore<T>`. Constructors and `drop()` remain pure; inference does not permit I/O while holding a lock. Type-changing recursive generic effect inference that cannot converge requires an explicit finite `uses` clause.
+Capability implementations inherit their operation contract even when a test adapter does no I/O. This includes shared-state capabilities such as `ExpiringStore<T>`. An unhandled error in main still fails checking; inferred propagation through a helper does not handle that failure.
 
 Outside main and test setup, every injected dependency is declared in the callable/class header. Calls forward the one compatible header dependency; multiple candidates require a clearer header. Constructor and interceptor dependencies are checked the same way. Body-level `resolve` is rejected with a fix to lift it into the header.
 
@@ -286,7 +292,7 @@ Nullable locals narrow after null checks, short-circuit conditions, match patter
 
 `match value` uses `when null`, `when some name`, `when true`, `when false`, or `when Type name`. Nullable and bool matches must cover every case. Open class/interface domains require `else`. Duplicate/unreachable cases and incompatible patterns are errors.
 
-An error satisfies Error. A callable declares specific errors with `returns T unless FileError and DomainError`. It can throw any value satisfying its declaration; declaring Error accepts any Error implementation. Calls must catch or propagate all effective errors, including interceptor layers.
+An error satisfies Error. A body infers escaping errors. A bodyless signature or explicit bound names specific errors with `returns T unless FileError and DomainError`. It can throw any value satisfying its declaration; declaring Error accepts any Error implementation. Calls must catch or propagate all effective errors, including interceptor layers; executable callers infer propagation when unless is omitted.
 
 `start` evaluates its receiver and arguments immediately; their errors belong to the scheduling statement. The scheduled operation's errors belong to a `wait for` or its owning scope's implicit join. Unobserved sibling failures can reach any wait in that group. Grouped waits observe every selected child, including cancellation cleanup, and rethrow the first failure. A helper awaiting a `Task<T>` parameter declares or handles `Error`, since that public type does not specify a narrower error contract yet.
 
@@ -312,7 +318,7 @@ import FileReader from august.io
  * @return UTF-8 text.
  * @throws FileError Reading failed or the text is invalid.
  */
-load(resolve FileReader files, string path) returns string uses files.read unless FileError:
+load(resolve FileReader files, string path):
     return files.read(path=path)
 ```