@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/language-design-audit.md

@@ -2,7 +2,7 @@
 
 ## Readability audit, September 29, 2026
 
-August 0.19 uses ASD-STE100 as guidance for plain technical explanations. The language keeps local behavior and neighboring contracts in view. The deterministic [spec compiler](specifications.md) extends that context to readers who do not read code.
+August 0.20 uses ASD-STE100 as guidance for plain technical explanations. The language keeps local behavior and neighboring contracts in view. The deterministic [spec compiler](specifications.md) extends that context to readers who do not read code.
 
 | Finding | Change |
 | --- | --- |

package/docs/learn/data-and-errors.md

@@ -0,0 +1,77 @@
+---
+prev:
+  text: Values and functions
+  link: /learn/values-and-functions
+next:
+  text: Modules and dependencies
+  link: /learn/modules-and-dependencies
+---
+
+# Data and failures
+
+A number alone does not explain every result. An order summary has named data, and an invalid order may need a failure rather than a zero total. This project introduces both.
+
+Create a new folder and save these two files in it:
+
+**main.aug**
+
+```aug project=book-data file=main.aug
+import Order and InvalidQuantity and summarize from orders
+
+try:
+    order = summarize(price=7, quantity=3)
+    print(value=order.total)
+    summarize(price=7, quantity=-1)
+catch InvalidQuantity error:
+    print(value="Quantity must be positive")
+
+Map<int, string> names = {1: "Ada"}
+match names.get(key=2):
+    when null:
+        print(value="No name for this identifier")
+    when some name:
+        print(value=name)
+```
+
+**orders.aug**
+
+```aug project=book-data file=orders.aug
+/** An immutable order summary. */
+record Order(int quantity, int total)
+
+/** Raised when an order quantity is not positive. */
+InvalidQuantity(int value) implements Error:
+    pass
+
+/** Reject nonpositive quantities and return the calculated summary. */
+summarize(int price, int quantity):
+    if quantity <= 0:
+        throw InvalidQuantity(value=quantity)
+    return Order(quantity, total=price * quantity)
+```
+
+`aug run .` prints:
+
+```text
+21
+Quantity must be positive
+No name for this identifier
+```
+
+## Keep data immutable
+
+`record Order(int quantity, int total)` declares data with two named fields. Its constructor uses labels just like a function. After construction those fields are immutable. Reading `order.total` does not copy the whole object.
+
+Use a record for a value whose meaning is its data. A class implements an interface and provides behavior; [the next chapter](modules-and-dependencies.md) uses one to supply a service. Records have limits on the types they can store; the [reference](../reference.md#classes-records-and-local-state) gives the complete rule.
+
+## Make failure part of the contract
+
+The throw tells the compiler that `summarize` can fail with `InvalidQuantity`. Its return expression supplies the `Order` result type. Hints, hover, and the compiled spec show this contract without repeating it in the header. `InvalidQuantity` is a class that implements `Error` and carries the rejected value. The caller must catch the failure or propagate it through an inferred or explicit contract. Main must handle it. In this application, `try` contains the calls and `catch` prints a message when the second call fails. Operations after a throw in that block do not run.
+
+Try removing the catch while keeping a bare call to `summarize` in `main.aug`. `aug check .` should report the unhandled error. Restore the example afterward. A checked failure tells you what a call can raise; it does not decide how your application should recover.
+
+## Distinguish a value from null
+
+A map lookup may find nothing. `names.get(key=2)` returns `optional string`, which means a string or null. `match` handles those alternatives explicitly. The `some name` branch supplies a non-null string named `name`.
+
+There is no separate missing state. Omitted optional inputs also become null. Use null when absence is an ordinary outcome; use a checked failure when the operation cannot meet its contract. [Matching and failures](../reference.md#null-matching-and-checked-failures) covers the detailed rules.

package/docs/learn/index.md

@@ -0,0 +1,30 @@
+---
+next:
+  text: Your first project
+  link: /getting-started
+---
+
+# The August book
+
+This book teaches you to read, write, and change August programs. It assumes you have written code in another language. You do not need to know C to follow the lessons; the toolchain uses a C compiler when you run a program.
+
+Start with a working application. Then add one idea at a time: labeled inputs, data and failures, module boundaries, dependencies, and controlled mutation. Each chapter contains a complete small project. Save its files together, run the commands, and compare your result with the output shown.
+
+## Read in order
+
+| Chapter | What you will do |
+| --- | --- |
+| [Your first project](../getting-started.md) | Install the toolchain, run a greeting, test it, and generate its specification. |
+| [Values and functions](values-and-functions.md) | Write a calculation and read labeled calls and conditions. |
+| [Data and failures](data-and-errors.md) | Return an immutable record, distinguish null from a value, and recover from a checked failure. |
+| [Modules and dependencies](modules-and-dependencies.md) | Export a folder's public surface and supply an implementation at startup. |
+| [State and tests](state-and-tests.md) | Change an object through a borrow and verify that test setup is fresh for each case. |
+| [Change an unfamiliar module](../guides/change-a-module.md) | Trace a dependency, make a bounded change, and review its tests and updated spec. |
+
+Chapters use indentation to keep the first examples compact. [Indentation and braces](../reference.md#blocks-and-statement-boundaries) have the same meaning, and the [gallery](../examples/index.md) displays both. Semicolons are optional. These are syntax choices; they do not change an application's contracts.
+
+## Use the rest of the documentation
+
+The [task guides](../guides/index.md) cover testing, services, packages, specifications, and measurement. The [language reference](../reference.md) states detailed rules, including cases these lessons leave for later. Library API pages describe exported operations. You can use those pages without reading the book from beginning to end.
+
+August is still experimental. The lessons teach the implemented language; [readiness](../production-readiness.md) describes the limits of deploying it. The lessons' complete source examples are checked and run by the repository's documentation tests.

package/docs/learn/modules-and-dependencies.md

@@ -0,0 +1,73 @@
+---
+prev:
+  text: Data and failures
+  link: /learn/data-and-errors
+next:
+  text: State and tests
+  link: /learn/state-and-tests
+---
+
+# Modules and dependencies
+
+An import should lead a reader to a small public contract. This project moves the greeting into its own folder and selects its implementation in the application entry point.
+
+Create a `greeting` folder beside `main.aug`:
+
+```text
+hello/
+  main.aug
+  greeting/
+    export.aug
+    greeter.aug
+```
+
+**main.aug**
+
+```aug project=book-modules file=main.aug
+import Greeter and FriendlyGreeter from greeting
+
+implement Greeter with FriendlyGreeter
+resolve Greeter to greeter
+print(value=greeter.greet(name="August"))
+```
+
+**greeting/export.aug**
+
+```aug project=book-modules file=greeting/export.aug
+export Greeter from greeter
+export FriendlyGreeter from greeter
+```
+
+**greeting/greeter.aug**
+
+```aug project=book-modules file=greeting/greeter.aug
+/** Provide a greeting for a named person. */
+interface Greeter:
+    greet(string name) returns string
+
+FriendlyGreeter() implements Greeter:
+    greet(string name):
+        return "Hello, " + name + "!"
+```
+
+Run `aug check .` and `aug run .`. The output is `Hello, August!`.
+
+## Choose what the folder exposes
+
+`export.aug` is the folder's public boundary. A file outside `greeting` can import the names listed there. It cannot reach other declarations in that folder merely by knowing their paths. Within a folder, sibling files also need explicit imports. A folder without `export.aug` exposes no names across its boundary.
+
+Try removing the export line for `FriendlyGreeter`. The import in `main.aug` should fail. Restore it after running `aug check .`. This is a boundary check; a private name beginning with `_` cannot be exported at all.
+
+## Select behavior at startup
+
+The interface describes the operation available to the caller. `FriendlyGreeter` implements that contract. `implement Greeter with FriendlyGreeter` selects the provider, and `resolve Greeter to greeter` obtains it for startup work.
+
+Elsewhere in an application, injected dependencies appear as `resolve` inputs in a class or function header. For example, `Worker(resolve Logger logger)` receives the configured logger without a caller supplying that argument. An ordinary `Logger logger` input must be passed by label. See [a complete constructor-injection example](../examples/new-syntax/index.md).
+
+Reading the entry point tells you the application's dependency choices. Reading a callable's header tells you its required dependencies. The compiler checks the binding graph before execution; a missing or cyclic dependency fails checking.
+
+## Follow a dependency
+
+Run `aug spec .` and read `main.aug.md`. Follow its links to the greeting's explanation, then read `greeting/export.aug.md` to see the public surface. In VS Code, Ctrl-click `from` or the module path to open the source or export file. This is the workflow you can use in a larger unfamiliar project too.
+
+Keep exports narrow as a folder grows. Add an implementation to the public surface when its caller needs to compose it. Keep helpers private and explain design intent beside the declaration. [The next chapter](state-and-tests.md) adds state and tests while preserving that local view.

package/docs/learn/state-and-tests.md

@@ -0,0 +1,71 @@
+---
+prev:
+  text: Modules and dependencies
+  link: /learn/modules-and-dependencies
+next:
+  text: Change an unfamiliar module
+  link: /guides/change-a-module
+---
+
+# State and tests
+
+Some objects need to change. A counter is a small example: callers can read its value, and one operation advances it. This project makes that change visible both in the contract and at the call site.
+
+Create a new folder and save these two files in it:
+
+**main.aug**
+
+```aug project=book-state file=main.aug
+import Counter from counter
+
+counter = Counter(initial=3)
+borrow counter:
+    counter.increment()
+print(value=counter.value())
+```
+
+**counter.aug**
+
+```aug project=book-state file=counter.aug
+interface Count:
+    increment() changes self
+    value() returns int
+
+Counter(mutable int initial to _count) implements Count:
+    increment():
+        _count = _count + 1
+
+    value():
+        return _count
+
+test Counter counter:
+    when incrementing:
+        counter = Counter(initial=3)
+        it advances:
+            borrow counter:
+                counter.increment()
+            assert(counter.value() == 4)
+
+        it starts_fresh:
+            assert(counter.value() == 3)
+```
+
+`aug run .` prints `4`. `aug test .` runs two cases. Both should pass.
+
+## Read before you borrow
+
+`mutable int initial to _count` gives the constructor a public input named `initial` and stores it in a private mutable field named `_count`. The interface's `changes self` permits `increment` to change the receiving object. The implementation infers that mutation from its assignment and inherits the read method's result type, so neither clause needs to be repeated.
+
+`borrow counter` grants mutable access for that block. The following call to `value()` only reads, so it needs no borrow. Read access shares a reference; it does not require copying the counter. Try moving `counter.increment()` outside the borrow block. `aug check .` should reject the mutation without permission. Restore the borrow before running again.
+
+This lesson uses a managed object. August also has ownership transfer and scoped cleanup. Learn those when your program needs them from [the ownership reference](../reference.md#ownership-and-read-access) and [complete lifetime examples](../examples/ownership-transfer/index.md).
+
+## Keep the behavior test nearby
+
+`test Counter counter` identifies the class and the subject variable. The setup inside `when incrementing` constructs the subject. Each `it` case gets fresh setup; the second case still sees `3` even though the first case incremented its own counter.
+
+Tests follow normal privacy rules. They verify behavior through `increment` and `value`, rather than reaching into `_count`. A case must execute an assertion. Test bodies are checked with the program, but are excluded from production executables.
+
+Change the first expected result to `5`, run `aug test .`, and inspect the failure's file and line. Restore `4`, rerun the tests, and generate the spec. You now have three views of the same behavior: the contract, executable cases, and a readable explanation.
+
+Use [the testing guide](../testing.md) when you need rows, fixtures, test adapters, filtering, or coverage. Continue with [a guided module change](../guides/change-a-module.md) to apply these tools in a larger project.

package/docs/learn/values-and-functions.md

@@ -0,0 +1,62 @@
+---
+prev:
+  text: Your first project
+  link: /getting-started
+next:
+  text: Data and failures
+  link: /learn/data-and-errors
+---
+
+# Values and functions
+
+In the first project, an interface and its implementation produced a greeting. A calculation that needs no dependency can be an ordinary function. This chapter calculates an order total.
+
+Create a new folder with these two files. Continue using the published CLI from the first chapter.
+
+**main.aug**
+
+```aug project=book-functions file=main.aug
+import total from prices
+
+int price = 7
+int quantity = 3
+print(value=total(price, quantity))
+print(value=total(quantity=0, price))
+```
+
+**prices.aug**
+
+```aug project=book-functions file=prices.aug
+/** Calculate the price for a positive quantity; otherwise return zero. */
+total(int price, int quantity):
+    if quantity > 0:
+        return price * quantity
+    return 0
+```
+
+Run `aug check .`, then `aug run .`. The output is:
+
+```text
+21
+0
+```
+
+## Read the call
+
+`int price = 7` gives the value a type and a name. `int price to 7` means the same thing. You can omit the type when it can be inferred, as in `price = 7`.
+
+Every call input has a label. `total(price, quantity)` is shorthand for `total(price=price, quantity=quantity)`: the local names match the labels. The second call supplies a different quantity. Labels let you reorder inputs without making the reader guess which argument is which.
+
+The declaration begins with the function's name; it needs no `function` keyword. The compiler infers an integer result from its return expressions. VS Code shows `returns int` beside the header as a hint; it is absent from saved source. You can write a return type to require a particular result. This function reads its inputs and calculates a value. It has no dependency or mutable state.
+
+## Read the decision
+
+`if quantity > 0` chooses the first return when the quantity is positive. That return ends the call. Otherwise execution reaches `return 0`. Every path in a function with a non-void result must return or throw.
+
+Boolean conditions use `and`, `or`, and `not`. For example, `price > 0 and quantity > 0` requires both comparisons to hold. `and` and `or` short-circuit: the second operand runs only when the first operand makes it necessary.
+
+## Try a change
+
+Change the first quantity to `4`. Run the program and check that the first result is `28`. Then change the second call's `quantity` label to `amount` and run `aug check .`. That call should fail checking because `total` has no input named `amount`. Restore the label before continuing.
+
+Run `aug spec .` and read `prices.aug.md`. It should explain the two return paths. The generated text describes the code; your comment explains why a nonpositive quantity produces zero. [The next chapter](data-and-errors.md) makes an invalid input an explicit failure instead.

package/docs/lesson-failures.json

@@ -0,0 +1,8 @@
+[
+  {"project":"getting-started","file":"main.aug","before":"greet(name=\"August\")","after":"greet(person=\"August\")","diagnostic":"has no parameter person"},
+  {"project":"book-functions","file":"main.aug","before":"quantity=0","after":"amount=0","diagnostic":"has no parameter amount"},
+  {"project":"book-data","file":"main.aug","source":"import summarize from orders\nsummarize(price=7, quantity=3)\n","diagnostic":"Unhandled InvalidQuantity"},
+  {"project":"book-modules","file":"greeting/export.aug","before":"export FriendlyGreeter from greeter\n","after":"","diagnostic":"does not export FriendlyGreeter"},
+  {"project":"book-state","file":"main.aug","before":"borrow counter:\n    counter.increment()","after":"counter.increment()","diagnostic":"requires borrow counter"},
+  {"project":"book-state","file":"counter.aug","before":"assert(counter.value() == 4)","after":"assert(counter.value() == 5)","command":"test","diagnostic":"advances"}
+]

package/docs/maintaining-docs.md

@@ -2,6 +2,8 @@
 
 Documentation is part of a language change. The canonical wiki is this repository's `docs` directory, reviewed and versioned with the compiler. GitHub Pages renders these same files; an independently edited GitHub Wiki would create a second source of truth.
 
+For writing and navigation, use [the editorial guide](writing-docs.md). The repository's `.agents/skills/maintain-august-wiki/SKILL.md` routes agents through that guide and this workflow. `AGENTS.md` requires it for documentation and behavior changes. The [research note](research/wiki-editorial-design.md) explains the source material and the decisions applied here.
+
 ## Where to make a change
 
 | Change | Update in the same commit |
@@ -9,13 +11,21 @@ Documentation is part of a language change. The canonical wiki is this repositor
 | Syntax, type/effect/ownership/DI rules | `docs/reference.md`, relevant grammar/testing/web guide and `src/help.ts` |
 | Public library signature or behavior | Javadoc beside its declaration in `src/stdlib`, the relevant guide and gap ledger |
 | Diagnostic or editor behavior | `src/help.ts`, diagnostics/tooling guide and VS Code changelog |
-| CLI, packages, configuration or supported platform | Tooling/packages/releasing guide and package metadata |
+| CLI, packages, configuration or supported platform | Tooling/packages/releasing guide, Docker and Dev Container recipes, and package metadata |
 | Completed or deferred feature | Implementation map, gap ledger and changelog |
 
 Public comments should explain observable behavior, named inputs, errors, side effects, and limits. Keep dependencies explicit in examples. Record incomplete capabilities in the gap ledger; do not imply that an unimplemented proposal is usable.
 
+Container guides install the published CLI and prepare its native dependencies. Keep their pinned CLI version, build tools, native library paths, and editor cache setting aligned with the release. Verify the HTTP application image and run the starter's check/run/test/spec workflow as the Dev Container's non-root user. State any verification mount substitutions: a Docker engine that cannot share local folders can test execution in an isolated volume, but that does not verify the default VS Code bind mount or editor port forwarding.
+
+For dependency-setup changes, run `npm run test:setup-cold` after preparing the pinned downloads. It builds crypto and HTTP through an aliased empty cache, runs a digest, and serves a real HTTP response. The fast first-run suite covers JSON/tasks, downloads, offline reuse, packages, and cache concurrency. Verify the installed package too; source execution alone does not prove that setup helpers ship in the npm archive.
+
+The installed-package gate uses an isolated npm cache. Its first installation fetches production dependencies; its later global installation runs offline from that cache. This checks both first use and reuse without relying on packages cached by the contributor's machine.
+
 ## Generated reference
 
+The gallery generator also creates deterministic project archives in `docs/public/downloads`. Each archive includes source, configuration, and generated specs, with neighboring source packages when required. It excludes build state, installed dependencies, locks with temporary host paths, and credentials. Gallery tests extract every archive and check it as an independent project. Public guides use these downloads and the npm CLI; source-workspace commands belong in contributor documentation.
+
 ```sh
 npm run docs:generate
 npm run docs:check
@@ -24,17 +34,19 @@ npm run docs:build
 
 The API generator reads each `export.aug`, resolves the actual public declaration, and uses the same Javadoc/inherited documentation path as hover. It includes public methods and excludes private native helpers. The language constructs page comes from editor help and collection operation contracts. Commit generated Markdown so GitHub readers and package users can read it without building a site. CI rejects stale generated pages.
 
-The generator also runs the deterministic spec compiler for every standard-library source file. Commit these adjacent `src/stdlib/**/*.aug.md` files. Unlike public API pages, full source specs include private helpers and all local behavior. For application or third-party package source changes, run `aug spec PROJECT` and verify `aug spec PROJECT --check`. See [the user workflow](specifications.md).
+The generator also runs the deterministic spec compiler for every standard-library source file. Commit these adjacent `src/stdlib/**/*.aug.md` files and their managed `// aug-spec:` source pointers. Unlike public API pages, full source specs include private helpers and all local behavior. The generator builds explicit behavioral relations, plans sentences within their scopes, checks statement provenance, and lays out connected paragraphs. Keep author comments and dependency links concise instead of repeating signatures or Javadoc sections. For application or third-party package source changes, run `aug spec PROJECT` and verify `aug spec PROJECT --check`. See [the user workflow](specifications.md) and [the research rationale](research/code-to-natural-language.md).
 
 ## Repository example gallery
 
-`docs/example-projects.json` lists the complete projects shown in [the example gallery](examples/index.md), including the measured benchmark programs. `docs:generate` checks each application and its same-file tests, formats each file in indentation and braces styles, and runs the spec compiler. It publishes code and specs side by side under `docs/examples`, with dependency links that stay in the wiki. Long code lines wrap visually without changing copied source. It also refreshes adjacent example specs and their offline dependency copies. Generation uses temporary project copies; the package-consumer example installs its local dependency offline there. It does not edit example source or create package locks in the checkout.
+`docs/example-projects.json` lists the complete projects shown in [the example gallery](examples/index.md), including the measured benchmark programs. `docs:generate` checks each application and its same-file tests, formats each file in indentation and braces styles, and runs the spec compiler. It publishes code and specs side by side under `docs/examples`, with dependency links that stay in the wiki. Long code lines wrap visually without changing copied source. It also refreshes adjacent example specs, managed source pointers, and offline dependency copies. Generation uses temporary project copies. It installs dependencies declared by imports and configuration, preserving committed revision locks. Git sources must be cached or reachable during preparation; spec generation itself stays offline. It preserves the source program and handwritten comments, and does not create package locks in the source workspace.
 
 Keep titles and descriptions in the catalog current when adding or changing an example. `docs:check` rejects source/spec drift. Gallery tests require every repository example and benchmark source to be represented, check both displayed syntax styles, and follow the wiki's generated links and declaration anchors. Readers can switch code style with a mouse or keyboard; their choice is kept between pages on the same browser.
 
 ## Executable examples
 
-Each runnable `aug` fence declares `project=NAME file=PATH`. A guide may spread one project across several fences. Add expected output/test counts to `docs/examples.json`. The documentation test assembles, checks, runs or builds, tests, formats, and checks those projects again. API signatures use `text` fences because a declaration header is not a complete application.
+A neighboring configuration fence can use `yaml project=NAME file=main.yaml`. Each runnable `aug` fence declares `project=NAME file=PATH`. A guide may spread one project across several fences. Add expected output/test counts to `docs/examples.json`. The documentation test assembles, checks, runs or builds, tests, formats, and checks those projects again. API signatures use `text` fences because a declaration header is not a complete application.
+
+The test discovers handwritten Markdown recursively, including the book and task guides. Generated API/gallery pages and hidden build folders have separate generation checks. Complete examples need expected output; identify fragments and intended failures in the prose. Maintain the chapter links and the public navigation when adding a lesson.
 
 ```sh
 node --test tests/documentation.test.mjs