@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/specifications.md

@@ -16,11 +16,21 @@ aug spec . --check
 | `export.aug` | `export.aug.md`: the folder's public surface. |
 | An installed dependency | A versioned explanation and source copy under `.aug-spec/`. |
 
-Successful `build`, `run`, and `bench` commands refresh these documents after native compilation. `aug pack` refreshes them before creating the source archive. `--check` writes nothing and exits with a failure if a document, dependency copy, or manifest is missing or stale. Use it in CI after `aug check`.
+After a source change, run `aug check .` and `aug test .`, regenerate with `aug spec .`, and review the source and spec diffs together. Use `aug spec . --check` in CI to detect drift without writing files. It fails if a document, source pointer, dependency copy, or manifest is missing or stale.
+
+Successful `build`, `run`, and `bench` commands also refresh specs after native compilation. `aug pack` refreshes them before creating the source archive. [Change an unfamiliar module](guides/change-a-module.md) walks through this workflow.
+
+Generation also adds one managed comment at the top of each project source file:
+
+```text
+// aug-spec: "orders.aug.md" explains this file. Read it before changes; refresh with aug spec.
+```
+
+This points readers and coding agents to the explanation before they edit the code. The compiler keeps the pointer current after a rename and preserves handwritten comments. It does not edit installed dependencies. Native builds add the pointer after checking and before C emission, so source maps use the correct lines. `aug spec --check` reports missing or outdated pointers without adding them.
 
 ## What the document explains
 
-The compiler describes labeled inputs, injected dependencies, return values, state changes, capabilities, and checked failures. It follows each local branch, loop, match, recovery path, and cleanup block. It includes private helpers and same-file tests. For endpoints, it describes routes, wire inputs, policies, middleware ordering, and configured HTTP behavior.
+Read a spec as a developer's explanation of the file. Each declaration has a short introduction and ordinary paragraphs about its behavior. The text explains inputs, dependencies, decisions, changes, results, and failures. It includes private helpers and same-file tests. Endpoint explanations include their routes, request inputs, policies, and HTTP outcomes.
 
 For example, this complete program uses two source files:
 
@@ -30,25 +40,29 @@ print(value=total(price=7, quantity=3))
 ```
 
 ```aug project=spec-guide file=prices.aug
-total(int price, int quantity) returns int:
+total(int price, int quantity):
     if quantity > 0:
         return price * quantity
     return 0
 ```
 
-Without any comments, the generated spec lists `total` near the top of the file, explains its two labeled inputs and `int` result, and then describes its behavior:
+Without any author comments, the generated explanation reads:
 
-> - If `quantity` is greater than `0`:
->   - Return `price` times `quantity`.
-> - Return `0`.
+> It takes `price` and `quantity` as integers. It returns `price` times `quantity` if `quantity` is positive, or `0` otherwise.
 
-The generated document preserves the actual branch structure and links to the full explanation of each used dependency. Javadoc, when present, appears after the generated behavior as **Author documentation**. It can explain intent that a compiler cannot infer, but readers do not need comments to follow the checked inputs, operations, and outcomes.
+Related work is explained together. Validation describes the requirements and what happens at the first failed check. HTTP results describe responses. Collection updates describe the values added or stored. Decisions, repeated effects, recovery, and cleanup remain part of the explanation.
 
-Optional contracts use `optional Type`. Specs describe two possible states: a value or null. Omitted inputs become null, so missing and explicit null follow the same branch. If an older program handles missing and null differently, combine those cases deliberately before using the syntax migration command.
+For a list of literal records, the spec names the fields once and gives the rows in their original order. Calls with computed inputs keep their individual explanations, so the shorter description does not hide work or dependencies.
+
+String construction appears as readable text such as `Hello, {name}!`. Braces mark inserted values; doubled braces represent literal braces. Parentheses preserve expression grouping when it changes the meaning. These are conventions in the explanation, not new August source syntax.
+
+Javadoc, when present, becomes part of the explanation: its summary introduces the declaration, parameter notes sit beside their inputs, and return and error notes sit beside those outcomes. Comments can explain intent that a compiler cannot infer, but readers do not need them to follow the checked inputs, operations, and outcomes.
+
+Optional contracts describe a value or null. Omitted inputs become null too. The [language reference](reference.md#null-matching-and-checked-failures) gives the matching and narrowing rules.
 
 ## Dependencies stay small and navigable
 
-Each file starts with a short map of its declarations and startup steps, then explains local behavior. A compact dependency section follows it. Each used operation shows its inputs, result, injected values, changes, capabilities, and failures, with a link to the complete explanation. Dependency implementation bodies belong in their own documents.
+The document follows the file's declarations and startup work. A short dependency section names only the types, operations, and fields used here, grouped by module. Their links lead to complete explanations. It does not repeat dependency signatures or implementation bodies. Built-in contracts link to the language reference.
 
 `import everything` stays valid. The spec lists the names and operations actually used by the file. Adding an unused export does not expand that list. VS Code hover still shows all names available from the import.
 
@@ -79,7 +93,9 @@ In VS Code, use **AugScript: Open Compiled Specification** to generate and previ
 
 ## Determinism and limits
 
-Generation is offline and deterministic for the same checked sources, configuration, installed dependency versions, and compiler version. It adds no timestamps or machine paths. It uses fixed templates and the compiler's semantic information.
+Generation is offline and deterministic for the same checked sources, configuration, installed dependencies, and compiler version. It adds no timestamps or machine paths. Explanations include inferred result types, mutations, dependencies, and escaping errors even when their clauses are absent from source. Explanations use checked contracts; the writer does not guess what an arbitrary function does from its name.
+
+The spec describes the checked program; it is not a proof that the implementation meets your domain's requirements. Review the explanation for clarity and intent, and use tests for behavior. [Research and implementation notes](research/code-to-natural-language.md) explain the generation approach and its evaluation limits.
 
 ASD-STE100 guides the wording. The output is best effort Simplified Technical English, without a claim of formal compliance. Native C boundaries are explained through their declared contracts and author documentation; the compiler does not infer a foreign implementation's internals. Shared numeric, ownership, and task rules link to the language reference.
 

package/docs/testing.md

@@ -1,23 +1,31 @@
 # Built-in unit tests
 
-Tests live in the same file as the declaration they describe. Class suites use `test ClassName subject`; function suites use `test functionName`. Tests are excluded from production executables, and no test package is required.
+Keep a behavior test in the same file as the declaration it checks. A reader can inspect the contract, implementation, and cases together. August's CLI runs these tests as native programs; you do not need a test package, and test bodies are excluded from production executables.
 
-Endpoint suites use `test endpoint endpointName client`. HttpTestClient enters the native routing and policy pipeline with explicit method, relative path, headers and optional Bytes body. Group bindings supply fresh test dependencies; production startup is excluded. See the [complete service and endpoint cases](web.md#endpoint-tests). Live sockets, TLS negotiation and disconnect behavior require transport tests separately.
+Use `test functionName` for a function or `test ClassName subject` for a class. This guide gives complete examples, then covers setup, filtering, and coverage. If testing is new to you in August, work through [State and tests](learn/state-and-tests.md) first. For HTTP, use [endpoint tests](web.md#endpoint-tests); they exercise routing and policies, while live sockets and TLS need separate transport tests.
 
 ## A complete function suite
 
+Save these three files in one folder. `aug run .` prints `3`; `aug test .` runs four cases. Three come from the input rows, and one calls the reusable fixture.
+
+**main.aug**
+
 ```aug project=testing-guide file=main.aug
 import add from math
 
 print(value=add(left=1, right=2))
 ```
 
+**fixtures.aug**
+
 ```aug project=testing-guide file=fixtures.aug
 /** A reusable, pure test input. */
 fixture seven() returns int:
     return 7
 ```
 
+**math.aug**
+
 ```aug project=testing-guide file=math.aug
 import seven from fixtures
 
@@ -39,10 +47,14 @@ test add:
             assert(add(left=seven(), right=0) == 7)
 ```
 
-Each tuple row becomes a separately listed and executed case. Row arity and types are checked. The row variables are local to that case. Fixtures are ordinary checked functions marked `fixture`; import them explicitly and declare any dependencies/effects. They create no implicit fixture scope and remain callable as ordinary functions.
+Each tuple row becomes a separately listed and executed case. The checker verifies its arity and types, and the row variables belong to that case. `fixture seven` is a reusable checked function. Import fixtures explicitly and declare their dependencies and effects, as you would for other functions. They remain callable outside tests and create no implicit setup scope.
 
 ## A complete class suite
 
+In a separate folder, save these two files. `aug run .` prints `1`, and `aug test .` runs two cases. Notice that the second case sees the initial counter value even though the first case increments its own subject.
+
+**main.aug**
+
 ```aug project=class-testing-guide file=main.aug
 import Counter from counter
 
@@ -50,6 +62,8 @@ counter = Counter(initial=1)
 print(value=counter.value())
 ```
 
+**counter.aug**
+
 ```aug project=class-testing-guide file=counter.aug
 interface Count:
     increment() changes self
@@ -72,7 +86,7 @@ test Counter counter:
             assert(counter.value() == 3)
 ```
 
-The subject header identifies a local class and the variable used to test it. It does not invoke the constructor; initialize that subject in setup or the case. Generic classes use concrete type arguments. Tests follow ordinary member privacy and cannot access private fields merely because they share the file.
+The subject header names a local class and its test variable. It does not construct the subject; setup does that here. Each case gets a new counter. Tests follow ordinary privacy rules, so sharing the source file does not grant access to `_count`. Test generic classes with concrete type arguments.
 
 ## Groups, setup, and dependencies
 
@@ -92,7 +106,7 @@ An uncaught checked error, a native crash, a nonzero exit, or a timeout fails th
 
 ## CLI and coverage
 
-Use `aug` when installed, or `node bin/aug.mjs` from this repository.
+Use `npx @greenpandastudios/aug-cli@next` in place of `aug` below, or use an installed `aug` command. See [Your first project](getting-started.md) for the npm workflow.
 
 | Command | Action |
 | --- | --- |

package/docs/tooling.md

@@ -1,15 +1,19 @@
 # Native builds and developer tooling
 
+Use this page to look up CLI commands, project configuration, native requirements, and editor behavior. If you need a running first project, follow [the book](learn/index.md). To use context reports during a change, follow [the module review guide](guides/change-a-module.md).
+
 ## CLI
 
-Use `aug` if installed or `node bin/aug.mjs` from the repository. Commands take a project folder, defaulting to the current directory. Editor commands also accept --file and --offset; use --help for the command inventory.
+Install `aug` once as shown in [Your first project](getting-started.md). Commands take a project folder, defaulting to the current directory. Editor commands also accept --file and --offset; use --help for the command inventory. `emit-ir`, `emit-llvm`, and the LLVM backend below require the unpublished development compiler until its matching preview release is available.
 
 | Command | Output |
 | --- | --- |
 | `check PROJECT [--json]` | Production, tests, module policy, documentation, and configuration diagnostics. |
 | `build PROJECT [--out NAME] [--json]` | Native path; JSON contains output and sourceMap. |
-| `run PROJECT -- args...` | Builds and runs; program stdout is preserved. |
+| `run [PROJECT] [--offline] -- args...` | Prepares declared packages and required native libraries, checks, compiles, and runs; program stdout is preserved. |
 | `emit-c PROJECT` | Generated C for inspection. |
+| `emit-llvm PROJECT` | Checked execution IR lowered directly to LLVM IR. |
+| `emit-ir PROJECT` | Verified August execution IR with typed root cells and source locations, for compiler contributors. |
 | `format PROJECT [--file PATH] [--write] [--json]` | Canonical source; --write updates files. |
 | `migrate PROJECT [--file PATH] [--write] [--json]` | Verified migration of rejected legacy syntax; preview by default. |
 | `spec PROJECT [--check] [--json]` | Adjacent Markdown specs and offline dependency explanations; --check detects drift without writing. |
@@ -18,23 +22,28 @@ Use `aug` if installed or `node bin/aug.mjs` from the repository. Commands take
 | `explain PROJECT --file PATH [--name NAME]` | Checked contracts, dependencies, layers, origins, tests, and module surface. |
 | `context PROJECT --file PATH [--name NAME] [--budget N]` | Bounded JSON context, including related declarations and source snippets. |
 | `lsp PROJECT` | Persistent language server over stdio. |
-| `package init DIRECTORY --name @owner/name` | Standalone source library with public exports, Javadoc and a same-file test. |
+| `package init DIRECTORY [--name @owner/name]` | Standalone source library with public exports, Javadoc and a same-file test. |
 | `package pack DIRECTORY` | Checked source archive ready for npm publishing or local installation. |
-| `install PROJECT [--frozen] [--offline]` | Explicit dependency snapshot and aug.lock.json. |
+| `add URL --as NAME [--project DIRECTORY]` | Installs a repository or archive under a short import alias. |
+| `install PROJECT [--frozen|--update] [--offline]` | Explicit dependency snapshot and aug.lock.json. |
 
-Warnings are nonblocking. Machine diagnostics carry severity, code, file, line, column, and message. check/build fail on errors; invalid command usage returns nonzero. Test failure returns nonzero and includes the case output.
+Warnings are nonblocking. Human diagnostics show the source line, a pointer, and help. Machine diagnostics carry severity, code, file, line, column, message, and help. check/build fail on errors; invalid options and missing option values return status 2. Test failure returns nonzero and includes the case output. Put runtime arguments after `--`, for example `aug run -- --port 8080`.
 
 ## Native standard libraries
 
-Web, crypto, JSON and tasks use pinned private C dependencies. On macOS or Linux, bootstrap them once from the compiler directory:
+The pending 0.21.0 compiler uses LLVM by default on macOS 14+ ARM64 and GNU/Linux x64/ARM64 with glibc 2.36+. `aug run` prepares source packages and the verified compiler/runtime pack, then builds and starts the application. `build`, `test`, and `bench` use the same backend; install source packages before running them in a fresh project. Consumers do not install Clang, LLVM, or an SDK. The published 0.20.1 CLI uses the older C workflow.
+
+The first LLVM run downloads the host's tools and prebuilt runtime components. JSON, tasks, crypto, and HTTP select components from that pack. A native package can add its own platform archives. Each download has a SHA-256 pin and size bound; later projects share verified cache entries. Installation never runs package build scripts or silently falls back to a source build. Missing artifacts and unsupported platforms include the failed requirement and a recovery step.
+
+For an offline run, prepare the project once with network access, then use:
 
 ```sh
-node scripts/bootstrap-native.mjs
+aug run --offline
 ```
 
-The script verifies archive SHA-256 hashes and builds under `.aug-native`; it does not install system packages. `--extract-only` supplies yyjson and minicoro for JSON/task-only programs. Web and crypto require the complete native build. Sources, dependency revisions and hashes are recorded in scripts/native-dependencies.lock.json; the installed manifest also records host platform and architecture. The full build has run on macOS ARM and Linux ARM; Linux x86-64 is checked by the Docker CI job.
+`--offline` prevents dependency downloads; it does not restrict application networking. `--frozen` requires recorded source, native artifact, compiler, and runtime selections for the current host. Prepare a project once online before using both flags. A cache for another architecture cannot satisfy the current host. See [native packages](native-packages.md) for supported platforms and exact qualification status.
 
-Set `AUG_NATIVE_HOME` to share a dependency directory across compiler copies. It names the directory containing `sources/` and `prefix/`, not the prefix itself. Bootstrap and compilation both honor it. For the bundled VS Code compiler, set `augscript.nativeHome` to that same absolute directory. The extension bundles the bootstrap scripts and lockfile; it does not bundle host-specific native libraries. Node 24+ and a C11 compiler remain requirements.
+Set `AUG_NATIVE_ARTIFACT_CACHE` to share verified downloads across compiler copies. The CLI and bundled VS Code compiler use the same LLVM default and archive pins. Native library deployment files load relative to the executable. The temporary `--backend c` reference needs a C11 compiler and source-build tools; `AUG_NATIVE_HOME` and `aug-native` configure that contributor workflow.
 
 The [web guide](web.md) covers transport/TLS/OpenAPI configuration and the working login app. The [gap ledger](web-library-gaps.md) records remaining native and language coverage.
 
@@ -63,16 +72,13 @@ lint:
 module_dependencies:
   - ".: app, contracts"
   - "app: contracts, shared"
-libraries:
-  - m
-library_paths:
-  - native/lib
 ```
 
 | Key | Contract |
 | --- | --- |
 | output | Executable name under .aug-build, or an absolute output path. |
 | optimization | debug (-O0) or release (-O2); both retain debug information. |
+| backend | llvm (default in 0.21.0) or the temporary c migration reference. |
 | block_style | Formatter braces or indent. |
 | indentation | Formatter spaces (four) or tabs. |
 | assignment | Formatter equals or to; both remain accepted source forms. |
@@ -82,7 +88,7 @@ library_paths:
 | max_dependencies | Import fan-out warning threshold, default 8. |
 | lint | Optional warnings listed above. |
 | module_dependencies | Allowed folder edges; same-folder imports and standard capabilities are allowed. |
-| libraries / library_paths | Linker library names and project-relative search directories. |
+| libraries / library_paths | C reference linker names and project-relative search directories; LLVM requires native package metadata. |
 
 An owner without a rule is unrestricted. . names the project root; folder names use slash paths. * matches any folder, and domain/* matches that folder and descendants. Rules use the first matching owner. Import cycles are always rejected independently of the policy.
 
@@ -110,7 +116,7 @@ announce(message="Hello from C")
 ```aug project=ffi-guide file=native.aug
 extern C puts(string value) returns c_int
 
-announce(string message) uses C.puts:
+announce(string message):
     unsafe:
         result = puts(value=message)
 ```
@@ -124,17 +130,19 @@ announce(string message) uses C.puts:
 | string | const char* (UTF-8, no NUL) |
 | void | void |
 
-C calls require unsafe, and callables declare uses C.function. Ordinary scalar extern declarations have no generics, resolve parameters, ownership transfer, nullable boundary types, or checked error clause. For libc functions taking C int, explicitly narrow with c_int; do not declare their boundary as int64_t.
+C calls require unsafe, and executable callers infer uses C.function. Ordinary scalar extern declarations have no generics, resolve parameters, ownership transfer, nullable boundary types, or checked error clause. For libc functions taking C int, explicitly narrow with c_int; do not declare their boundary as int64_t.
 
 Standard adapters use `extern C value` for the managed AugValue ABI. Each C argument and result must actually be AugValue; headers expose the declared capability effect and checked failures. `pure` asserts a trusted native implementation has no observable effects. These declarations are unsafe contracts, not automatic C bindings. Crypto, HTTP, JSON and time adapters demonstrate this narrow boundary in src/stdlib and runtime.
 
-The extern declaration must match the real native ABI. This version does not expose pointers, callbacks, binary buffers, arbitrary structs, or a C header importer.
+The extern declaration must match the real native ABI. For owned opaque handles and binary buffers, use [native package descriptors](native-packages.md); binding maintainers can check a reviewed descriptor against a C header with `aug bind header`. Ordinary scalar extern declarations do not expose pointers, callbacks or arbitrary structs.
 
 ## Source locations and debugging
 
-Native output lives under .aug-build. Generated C has #line locations for executable AugScript statements and extern declarations. Native compiler errors at those locations become NATIVE diagnostics. A successful build writes EXECUTABLE.augmap.json with compiler version, exact C arguments, source hashes, generated hash, and symbol origins.
+Native output lives under `.aug-build`. LLVM failures identify the August source location or failing artifact/link input. A successful build writes `EXECUTABLE.augmap.json` with compiler/runtime identities, hashes, selected artifacts and source symbols. C reference output uses `#line` locations and records its C arguments separately.
+
+Both development and optimized builds include source debug information: an adjacent dSYM on macOS, and DWARF in the ELF executable on Linux. The compiler pack supplies macOS `dsymutil`; consumers do not need Apple developer tools to create the dSYM. LLDB reads the C-compatible tagged storage, while files, locations and producer identify the August source. Optimized variables may be unavailable. Rich collection views and August expression evaluation remain unfinished.
 
-Every build uses -g. Use **Debug AugScript** in VS Code with LLVM lldb-dap on PATH, or configure augscript.lldbDapPath. The extension builds the project and launches the standard adapter. See the [VS Code debugger API](https://code.visualstudio.com/api/extension-guides/debugger-extension) and [LLDB DAP documentation](https://lldb.llvm.org/use/lldbdap.html).
+Use **Debug AugScript** in VS Code with LLVM lldb-dap on PATH, or configure augscript.lldbDapPath. The extension builds the project and launches the standard adapter. See the [VS Code debugger API](https://code.visualstudio.com/api/extension-guides/debugger-extension) and [LLDB DAP documentation](https://lldb.llvm.org/use/lldbdap.html).
 
 **AugScript: Debug in LLDB Terminal** works with an ordinary lldb executable. Example terminal commands:
 
@@ -144,13 +152,13 @@ run
 bt
 ```
 
-Debug information resolves source breakpoints. Variables currently display the C runtime's tagged representation; rich AugScript variable views, expression evaluation, and ownership-aware debugging are future work. This machine has LLDB but no lldb-dap, so the DAP launch path requires installing/configuring that adapter. The source-breakpoint smoke test resolved two locations; native launch then stalled on this host and was stopped, so interactive stepping and call-stack behavior remain unverified here.
+Debug information resolves source breakpoints. Variables currently display the C runtime's tagged representation; rich AugScript variable views, expression evaluation, and ownership-aware debugging are future work. Configure an LLDB DAP adapter to use the debug launch path. Native variables still use the runtime’s tagged representation; richer August views remain on the roadmap.
 
 AUG_TRACE_DROPS=1 enables runtime cleanup tracing to stderr for lifecycle verification; it is developer instrumentation, not a language I/O capability.
 
 ## Benchmarks
 
-`aug bench` compiles release C, runs warmups, then reports every sample, median, minimum, and p95 in milliseconds. Measurements include process startup and exclude compilation. The timeout bounds each native run.
+`aug bench` uses the selected backend's release mode, runs warmups, then reports every sample, median, minimum, and p95 in milliseconds. Measurements include process startup and exclude compilation. The timeout bounds each native run.
 
 See [performance and benchmark graphs](performance.md) for measured comparisons with C, Node and Python, peak memory, HTTP throughput, raw results, and reproducible commands. `npm run bench:compare` measures the fixed workloads under `benchmarks/`. The earlier [single-workload baseline](benchmarks.json) is preserved as historical evidence.
 
@@ -194,4 +202,10 @@ The language server implements the [LSP 3.17 protocol](https://github.com/Micros
 
 One server runs per project. Parsed modules and checked import closures are cached by source/configuration revision. Unrelated edits reuse the previous immutable semantic document; dependency edits invalidate its closure. Local files can be checked while main composition is incomplete. Whole-project check/build still validates all bindings and startup.
 
-Compiler and extension development dependencies use exact versions and lockfiles. Native maps record the selected C toolchain and inputs; C compiler/OS versions are environment requirements, not vendored binaries. User-authored source packages use npm archives/registry transport, exact versions, and `aug.lock.json`; [the package guide](packages.md) covers creation, installation, public imports and frozen CI builds.
+Compiler and extension development dependencies use exact versions and lockfiles. LLVM source maps record the compiler/runtime identities, target, source revision, native artifacts, executable, and debug files. Source packages use public repository URLs, local folders, or npm archives, with revisions and integrity in `aug.lock.json`; [the package guide](packages.md) covers creation, installation, public imports and frozen builds.
+
+## Inferred contract hints
+
+VS Code shows inferred results, mutations, capability operations, and escaping checked errors beside executable headers. Long capability/error lists collapse to counts; their tooltip shows the full contract. These hints use the checked project, including unsaved edits and imported declarations. They are display text; formatting and saving do not add them to source. Hover, signature help, `aug explain`, and compiled specs share the same contracts. Bodyless interfaces and foreign declarations keep explicit contracts.
+
+Hints are enabled by default. Disable `augscript.inferredContractHints` to hide them, or use VS Code’s `editor.inlayHints.enabled` setting. The language server supports `textDocument/inlayHint` with range filtering for other editors.

package/docs/weather-api.md

@@ -0,0 +1,65 @@
+# Build a weather API
+
+Create a service that returns five simulated weather forecasts as JSON. This example follows the familiar weather API shape from Microsoft's ASP.NET Core starter: a date, Celsius and Fahrenheit temperatures, and a summary. It uses fixed values so you can reproduce its responses and tests. It does not fetch live weather.
+
+You need the [August toolchain](packages.md#npm-registry) and the native HTTP build prerequisites described in the [web guide](web.md). You can also use a [Dev Container](dev-containers.md).
+
+## Start the service
+
+```sh
+npx @greenpandastudios/aug-cli@next init weather --template weather
+cd weather
+npx @greenpandastudios/aug-cli@next run
+```
+
+The first run prepares the required native dependencies and starts the server on port 8787. Keep it running, then open another terminal:
+
+```sh
+curl http://127.0.0.1:8787/weatherforecast
+```
+
+You should receive an array of five forecasts. Its first item is:
+
+```json
+{"date":"2026-01-01","temperatureC":0,"temperatureF":32,"summary":"Freezing"}
+```
+
+Open `http://127.0.0.1:8787/docs` for the API viewer, or `/openapi.json` for the generated OpenAPI document. The starter also includes `weather.http` with these requests for editors that support HTTP request files. Stop the server with Ctrl+C before starting another instance on the same port.
+
+## Read the two source files
+
+`main.aug` imports the endpoint and starts it:
+
+```text
+import weatherForecast from forecasts
+
+serve weatherForecast on port 8787
+```
+
+`forecasts.aug` declares the immutable `WeatherForecast` record, the endpoint, and its tests. The endpoint has no inputs and returns a list of records. August infers that result from its body, serializes it as JSON, and describes the same shape in OpenAPI. You do not need a controller class or a library dependency for this service.
+
+A record construction names each field, for example:
+
+```text
+WeatherForecast(
+    date="2026-01-01",
+    temperatureC=0,
+    temperatureF=32,
+    summary="Freezing"
+)
+```
+
+The endpoint's route is `GET /weatherforecast`. The test client exercises that route through the HTTP pipeline; it checks the JSON response and the rejection of another HTTP method. `main.yaml` enables OpenAPI and sets the document title and version.
+
+## Make a change and check it
+
+In `forecasts.aug`, change the first summary from `Freezing` to `Cold`. Run the application again and check that the first response changed. Then run:
+
+```sh
+npx @greenpandastudios/aug-cli@next test
+npx @greenpandastudios/aug-cli@next spec
+```
+
+If you installed the CLI globally, the equivalent commands are `aug test` and `aug spec`. Open `forecasts.aug.md` to read the actual compiled explanation. The starter's `AGENTS.md` asks coding agents to read that explanation before changing the code.
+
+[Browse the complete weather project](examples/weather-api/index.md) to see the source beside its generated spec, switch between indentation and braces, or download the files. Continue with the [web guide](web.md) to accept typed inputs, return errors, render HTML, or stream a response. See Microsoft's [first web API tutorial](https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api) for the original starter context.

package/docs/web-library-gaps.md

@@ -18,7 +18,7 @@ This ledger records gaps discovered while implementing the confirmed web design
 | Public task error contracts | Task helpers should show their delayed failures in context. | Locally scheduled errors follow task aliases, collections, waits, exception paths and implicit joins. A helper accepting Task<T> must handle or declare Error; a public type spelling for a narrower delayed-error contract remains. |
 | Injected captures and owned shared payloads | Concurrent helpers must preserve dependency loans and resource lifetime. | The compiler tracks task reads through injected dependencies as well as written arguments and receivers. A native regression verifies that dropping an owned `Shared<T>` drops its transferred payload before later locals. Broader ownership and cancellation conformance work remains in the language roadmap. |
 
-Release review regressions cover duplicate scalar query/header/cookie/form inputs without process failure, inherited child deadlines, lock progress, owned resource lifetime, sibling and grouped cleanup errors, bounded response statuses, int64 action captures, complex and Json-valued forms, empty streams, and post-yield endpoint-test failures.
+Release review regressions cover duplicate scalar query/header/cookie/form inputs without process failure, inherited child deadlines, lock progress, owned resource lifetime, sibling and grouped cleanup errors, bounded response statuses, int64 action captures, complex and Json-valued forms, empty streams, and post-yield endpoint-test failures. Streaming HEAD preserves its headers and status when stopping the producer; a cleanup error before headers remains a 500. HEAD completes at its headers on HTTP/1.1 and HTTP/2, with its prepared response retained through session cleanup. Compressed disconnect checks cross managed collection pressure and verify server survival.
 
 ## Scope boundaries
 

package/docs/web.md

@@ -1,30 +1,47 @@
 # HTTP, server pages, and crypto
 
-HTTP endpoints are language declarations. `august.web` supplies explicit network, authentication, authorization, and logging capabilities; `august.crypto` supplies cryptographic adapters. August source owns routing contracts and application decisions. The native boundary owns transport, serialization, and cryptographic primitives.
+Build a service by declaring its routes in August and serving them from `main.aug`. The declarations describe how HTTP inputs become typed values and how results become responses. Your application selects authentication, authorization, and logging capabilities explicitly. The optional web and crypto packages provide adapters for native transport and cryptographic operations.
+
+This guide builds a service with JSON, a server-rendered page, a form action, and an event stream. Learn [modules and dependencies](learn/modules-and-dependencies.md) first if `implement` and `resolve` are unfamiliar. Full web and crypto runs need the [native bootstrap](tooling.md#native-standard-libraries). The service uses demonstration authentication; [the gap ledger](web-library-gaps.md) describes what remains before a production service claim.
 
 ## A complete service
 
-This project serves a protected JSON endpoint, an August page, a form action, and an event stream. The documentation gate builds it and runs its endpoint cases without starting a persistent server. Copy the files into one folder and run `aug run FOLDER` to listen on port 8080.
+Copy the following files into one folder and run `aug install`. `aug check .` checks the contracts and `aug test .` runs the three endpoint cases. `aug run .` starts the server on port 8080. The documentation gate builds the service and runs its tests; it does not leave a server running.
+
+Read `main.aug` first. It supplies the authentication and request-logging implementations, then serves the four named endpoints. Read `api.aug` for the JSON route and stream, `actions.aug` for the POST, and the page/view files for HTML.
+
+**main.yaml**
+
+```yaml project=web-guide file=main.yaml
+packages:
+  web: "https://github.com/GreenPandaStudios/augscript/src/stdlib/web#v0.19.0"
+```
+
+**main.aug**
 
 ```aug project=web-guide file=main.aug
 import readUser and events from api
 import home from pages
 import save from actions
 import DemoAuthentication from auth
-import Authentication and RequestLogger and WebRequestLogger from august.web
+import Authentication and RequestLogger and WebRequestLogger from web
 
 implement Authentication with DemoAuthentication
 implement RequestLogger with WebRequestLogger scoped
 serve readUser and events and home and save on port 8080
 ```
 
+**models.aug**
+
 ```aug project=web-guide file=models.aug
 record User(int id, string name)
 record UserInput(string name)
 ```
 
+**auth.aug**
+
 ```aug project=web-guide file=auth.aug
-import Authentication and Principal from august.web
+import Authentication and Principal from web
 
 /** A demonstration adapter. Replace its credential check for a real application. */
 DemoAuthentication() implements Authentication:
@@ -38,10 +55,12 @@ DemoAuthentication() implements Authentication:
                 return null
 ```
 
+**api.aug**
+
 ```aug project=web-guide file=api.aug
 import User from models
 import DemoAuthentication from auth
-import Authentication and RequestLogger and WebRequestLogger from august.web
+import Authentication and RequestLogger and WebRequestLogger from web
 
 /** Look up one user. Authentication runs before the identifier is decoded. */
 [LogRequest(logger=logger)]
@@ -49,7 +68,7 @@ import Authentication and RequestLogger and WebRequestLogger from august.web
 [RateLimit(requests=100, seconds=60)]
 [Timeout(milliseconds=1000)]
 [Compress]
-endpoint GET "/users/{id}" as readUser(int id from path, resolve Authentication auth, resolve RequestLogger logger) returns User uses auth.authenticate and logger.complete:
+endpoint GET "/users/{id}" as readUser(int id from path, resolve Authentication auth, resolve RequestLogger logger):
     return User(id, name="Ada")
 
 test endpoint readUser client:
@@ -78,15 +97,19 @@ test endpoint events client:
             assert(condition=response.headers.get(name="content-type") == "text/event-stream")
 ```
 
+**actions.aug**
+
 ```aug project=web-guide file=actions.aug
 import UserInput from models
-import redirect from august.web
+import redirect from web
 
 /** Accept a typed form and redirect after handling it. */
-endpoint POST "/users" as save(UserInput input from form) returns HttpResponse<string> unless HttpError:
+endpoint POST "/users" as save(UserInput input from form):
     return redirect(location="/")
 ```
 
+**views.aug**
+
 ```aug project=web-guide file=views.aug
 import User from models
 import save from actions
@@ -98,6 +121,8 @@ NewUser() returns Html unless HttpError:
     return <form onSubmit={handle save(input from form)}><label>Name <input name="name" required /></label><button type="submit">Save</button></form>
 ```
 
+**pages.aug**
+
 ```aug project=web-guide file=pages.aug
 import User from models
 import UserCard and NewUser from views
@@ -119,7 +144,7 @@ JSON bodies decode into concrete immutable records. `optional T` allows a value
 
 An ordinary return becomes the documented status and a JSON, Html, or Bytes representation. `HttpResponse<T>` selects status and immutable `Headers` explicitly. `Headers.with` appends a value, preserving repeated headers such as Set-Cookie; singular wire inputs reject duplicates. The `redirect` and `cookie` helpers validate header values. Cookie callers explicitly choose Secure and lifetime settings.
 
-Response status literals must range from 200 to 599; constructing a response with a dynamic status requires handling or declaring `HttpError`. Complex form fields use the same JSON schemas as body inputs: malformed JSON text returns 400 and a schema mismatch returns 422.
+Response status literals must range from 200 to 599. Constructing a response with a dynamic status can fail with `HttpError`; catch that failure or let it propagate through the inferred contract. Complex form fields use the same JSON schemas as body inputs: malformed JSON text returns 400 and a schema mismatch returns 422.
 
 `unless ErrorType with status CODE` declares an error response. Unexpected failures produce 500 with server-side error reporting. Default failures use [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html). OAuth endpoints in the proof return their protocol's JSON errors explicitly. HEAD suppresses the body; 204 and 304 suppress body and Content-Length. See the [gap ledger](web-library-gaps.md) for unimplemented HTTP behavior; this is not a claim of full protocol conformance.
 
@@ -129,20 +154,24 @@ The first written HTTP policy is outermost. Policies execute before wire decodin
 
 | Policy | Inputs and behavior |
 | --- | --- |
-| RequireLogin | `authentication=auth` maps an explicit `resolve Authentication auth`; declare `uses auth.authenticate`. A null identity returns 401. The adapter validates credentials. |
-| RequirePermission | Maps Authentication and Authorization dependencies plus a literal permission; denied access returns 403. Declare both capability operations. |
-| LogRequest | Maps `resolve RequestLogger logger` and `uses logger.complete`. Calls completion in reverse layer order after transport completion or disconnect. Disconnect status is 499 for logging. WebRequestLogger emits escaped JSON metadata without credentials or query strings. |
+| RequireLogin | `authentication=auth` maps an explicit `resolve Authentication auth`. The compiler includes `auth.authenticate` in the handler's inferred contract. A null identity returns 401. The adapter validates credentials. |
+| RequirePermission | Maps Authentication and Authorization dependencies plus a literal permission; denied access returns 403. Both capability operations appear in the inferred contract. |
+| LogRequest | Maps `resolve RequestLogger logger` and adds `logger.complete` to the inferred contract. Calls completion in reverse layer order after transport completion or disconnect. Disconnect status is 499 for logging. WebRequestLogger emits escaped JSON metadata without credentials or query strings. |
 | RateLimit | Literal requests and seconds; a bounded fixed-window counter per endpoint and trusted transport peer. It ignores client-supplied forwarding headers. Excess returns 429. |
 | Timeout | Literal milliseconds; handler, scoped tasks, streaming and transport share the deadline. Before output, timeout returns 504; after headers it terminates output. C calls finish before cooperative cancellation is observed. Buffered request reception precedes this deadline. |
 | Cors | Literal exact origins, optional request-header allowlist and credentials. A supplied disallowed origin returns 403. Preflight checks the selected route's method and requested headers. Wildcard cannot enable credentials. CORS is not authentication or CSRF protection. |
 | Compress | Negotiates gzip, respects an existing Content-Encoding, and skips bodyless statuses. Stream items use complete concatenated gzip members as permitted by [RFC 1952](https://www.rfc-editor.org/rfc/rfc1952.html). |
 
-Options are compile-time literals; dependency mappings must reference the canonical `august.web` capabilities. Cors and Compress may each appear once. Multiple deadlines choose the earliest. Custom interceptors retain their checked around/next contracts and written order.
+Options are compile-time literals. Import the policy interfaces from the web source package; the compiler checks their signatures against the native adapter contract. Cors and Compress may each appear once. Multiple deadlines choose the earliest. Custom interceptors retain their checked around/next contracts and written order.
 
 ## Streams and scoped tasks
 
 An endpoint may `streams ServerEvent<T>`, `streams Bytes`, or `streams Html`. `yield` supplies one item. Each pending encoded item is bounded to 64 KiB and sent under transport backpressure. A response has one consumer. Errors before headers become HTTP responses; later failures terminate output without appending a second error representation. Disconnect cancels the request and its children; `always` cleanup runs. The request DI scope survives through response completion.
 
+A HEAD request sends the GET response headers without a body. For a stream, the first yield establishes the response, then the producer stops and runs its cleanup. Intentional completion keeps the response status; a real cleanup failure still produces an error response. [HTTP HEAD semantics](https://www.rfc-editor.org/rfc/rfc9110.html#name-head).
+
+HEAD transport completes at its headers, including the stream-end flag for HTTP/2. Connection reuse does not turn a completed request into a disconnect log.
+
 `start fetch(...)` creates a task owned by its lexical scope. `wait for loadingUsers and loadingOrders to users and orders` waits in the stated result order; `wait for taskList` returns an ordered result list. `to`, `as`, and `=` result assignments are supported where the grammar permits them. Scope exit joins children; an unhandled child failure cancels siblings. Read-only frozen values can be shared without copying. Mutable captures are loaned until the task is observed. `lock shared as value` grants exclusive mutation and forbids nested locks, I/O, task starts and waits inside the locked region.
 
 Declare an owned resource directly in its task's `scope` block to keep it alive through implicit joining. A resource declared in a shorter nested block must be waited for before that block ends; the compiler rejects a live task borrow at that boundary. Unrelated owned cleanup does not join the enclosing scope's children. Pure loops under a lock finish or observe cancellation before another coroutine runs.
@@ -186,12 +215,19 @@ Crypto is an injected capability with GnuTlsCrypto as its native adapter. It pro
 
 `signJwt` requires an explicit key id and token type. `verifyJwt` accepts the configured RS256/key-id/type profile, rejects unsupported JOSE fields, verifies the signature before exposing claims, and follows no token-provided URL. The consuming protocol still validates issuer, audience, times, nonce and token purpose. The implementation follows the fixed-algorithm approach described in [JWT best current practices](https://www.rfc-editor.org/rfc/rfc8725.html).
 
-The [same-app login example](../examples/oidc-login/README.md) contains an OpenID Connect provider and relying party in one August application. It uses real loopback discovery, authorization, token, JWKS and UserInfo endpoints, Authorization Code with S256 PKCE, browser-bound state/nonce/CSRF, and a distinct application-session JWT with live revocation. The UI signs in and signs out through typed actions. See [OpenID Connect Core validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) and [S256 PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
+The [same-app login example](examples/oidc-login/index.md) contains an OpenID Connect provider and relying party in one August application. It uses real loopback discovery, authorization, token, JWKS and UserInfo endpoints, Authorization Code with S256 PKCE, browser-bound state/nonce/CSRF, and a distinct application-session JWT with live revocation. The UI signs in and signs out through typed actions. See [OpenID Connect Core validation](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation) and [S256 PKCE](https://datatracker.ietf.org/doc/html/rfc7636).
+
+Download and extract [the login project](examples/oidc-login/index.md#try-this-project). From the folder containing it:
+
+```sh
+cd oidc-login
+aug run
+```
+
+In another terminal, run the signed-claim tests from the same project folder:
 
 ```sh
-node scripts/bootstrap-native.mjs
-node bin/aug.mjs run examples/oidc-login
-node bin/aug.mjs test examples/oidc-login --group signed_identity_claims
+aug test --group signed_identity_claims
 ```
 
-Open http://127.0.0.1:8787 and sign in as **ada** with **august-demo**. `/me` returns the protected identity; `/docs` exposes endpoint contracts. The [gap ledger](web-library-gaps.md) distinguishes this verified development profile from broader provider, library and runtime support.
+The first run prepares the native HTTP and crypto libraries automatically; later runs reuse them. [Install August](getting-started.md) first if `aug` is not available. Open http://127.0.0.1:8787 and sign in as **ada** with **august-demo**. `/me` returns the protected identity; `/docs` exposes endpoint contracts. The [gap ledger](web-library-gaps.md) distinguishes this verified development profile from broader provider, library and runtime support.