@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/language-conformance.md

@@ -1,6 +1,6 @@
 # Ownership and task conformance
 
-August 0.19 checks ownership before compiling and joins every child before its `scope` ends. This page records the behavior exercised by the [language conformance suite](../tests/language-conformance.test.mjs). It is a candidate 1.0 contract; the [compatibility policy](compatibility.md) takes effect only with a 1.0 release.
+August 0.20 checks ownership before compiling and joins every child before its `scope` ends. This page records the behavior exercised by the [language conformance suite](../tests/language-conformance.test.mjs). It is a candidate 1.0 contract; the [compatibility policy](compatibility.md) takes effect only with a 1.0 release.
 
 ## What the compiler guarantees
 
@@ -27,4 +27,10 @@ The compiler tracks object origins through aliases and fields. It can reject cod
 
 Tasks currently run cooperatively on one OS thread. A long loop reaches cancellation at compiler-inserted checkpoints. `Shared<T>` is the explicit path for synchronized mutable state. The runtime does not yet promise parallel CPU execution.
 
+Scheduling an owned input transfers its cleanup responsibility immediately. If
+a sibling cancels the child before entry, the scheduler releases that input.
+The checker rejects owned task results, including inferred `Task<T>` results,
+until the public task type has an owned-result transfer contract. Both backends
+exercise these cases in the concurrency suite.
+
 Run the focused suite with `node --test tests/language-conformance.test.mjs`. The full repository test command also runs existing [concurrency](../tests/concurrency.test.mjs), ownership, errors, formatter, and generated-spec tests. This suite is growing through adversarial review; a green run does not establish complete ownership safety. The [roadmap](roadmap.md) keeps the language semantics gate open until that review and native CI finish.

package/docs/language-constructs.md

@@ -342,7 +342,7 @@ Checked failure for division by zero. int arithmetic otherwise wraps in the sign
 around(Type input) returns Type { return next(); }
 ```
 
-The required entry point of an interceptor. Its parameters select target arguments, and its result must fit the target return type. Omit `returns` for void. It may validate, override mapped arguments, inspect the result, throw a checked error, or return early. Declare generic parameters on the interceptor header. Helper methods can be declared alongside around.
+The required entry point of an interceptor. Its parameters select target arguments, and its result must fit the target return type. A forwarding body can omit returns and inherit the target result. It may validate, override mapped arguments, inspect the result, throw a checked error, or return early. Declare generic parameters on the interceptor header. Helper methods can be declared alongside around.
 
 ## as
 
@@ -426,7 +426,7 @@ Signed 32-bit C int. Convert explicitly with c_int(value=number), which raises C
 capability Console { write(string value) uses Console.write }
 ```
 
-Declare an interface for an external effect. Import the standard Console, FileReader, FileWriter and Arguments contracts from august.io, select adapters in main, and receive them through resolve parameters. Operations remain visible in uses clauses and can be replaced in tests.
+Declare an interface for an external effect. Import the standard Console, FileReader, FileWriter and Arguments contracts from august.io, select adapters in main, and receive them through resolve parameters. Operations stay visible in inferred hints, hover and specs and can be replaced in tests.
 
 ## catch
 
@@ -442,7 +442,7 @@ Handle a thrown error from the preceding `try` block. The caught value is availa
 increment() changes self
 ```
 
-Declare observable mutation of self or a borrowed input. Callers must provide mutable access. Ordinary functions and methods are pure by default; changing a local variable or a fresh local object does not change caller-owned state.
+Describe observable mutation of self or a borrowed input. Bodies infer changes when omitted; callers still need mutable access. Bodyless interface contracts declare permitted mutation. Local variables and fresh local objects do not change caller-owned state. An explicit clause limits the body.
 
 ## class
 
@@ -474,7 +474,7 @@ Negotiate gzip from Accept-Encoding, respecting q=0. Buffered output and each bo
 ConversionError implements Error
 ```
 
-Checked failure when c_int(value=number) cannot fit the signed 32-bit C int range. Catch it or declare unless ConversionError.
+Checked failure when c_int(value=number) cannot fit the signed 32-bit C int range. Catch it or let it propagate.
 
 ## cookie
 
@@ -566,7 +566,7 @@ Inherit methods from one or more interfaces. Class inheritance is not supported.
 extern C name(Type arg) returns Type
 ```
 
-Declare a C function. Calls require unsafe and external callables declare uses C.name. int maps to int64_t, c_int to signed 32-bit int, float to double, bool to C bool, and string to a temporary UTF-8 const char pointer. Foreign code must respect the declared ABI and cannot retain managed pointers.
+Declare a C function. Calls require unsafe and executable callers infer uses C.name. int maps to int64_t, c_int to signed 32-bit int, float to double, bool to C bool, and string to a temporary UTF-8 const char pointer. Foreign code must respect the declared ABI and cannot retain managed pointers.
 
 ## false
 
@@ -582,7 +582,7 @@ Boolean false. and and or evaluate the right side only when needed. Conditions r
 FileError
 ```
 
-Built in checked error from text file operations. Catch it or declare `unless FileError`.
+Checked failure from text file operations. Catch it or let it propagate.
 
 ## fixture
 
@@ -654,7 +654,7 @@ Names the source of an import or export. Dotted paths cross folders; each crosse
 No function keyword
 ```
 
-Functions and methods start with their name: `greet(string name) { ... }` or `greet(string name) returns string;`. Remove the old `function` prefix. Parameters use `Type name` order and callers use labels. Omit `returns` for a `void` result.
+Functions and methods start with their name: greet(string name) { ... }. Remove the old function prefix. Parameters use Type name order and callers use labels. Bodies infer omitted returns, changes, uses and unless clauses; declarations without a body keep explicit contracts.
 
 ## handle
 
@@ -750,7 +750,7 @@ Marks a declaration as a class and lists the interfaces it satisfies. Every clas
 import Logger and ConsoleLogger from logging
 ```
 
-Bring public declarations into this file. Use `and` for several names, or `import everything from logging` for all public sibling declarations or folder exports. Imported dependencies are never re-exported implicitly. Names or modules starting with `_` stay private. A sibling module uses its filename without `.aug`; a folder exposes only names listed in `export.aug`.
+Bring public declarations into this file. Use `and` for several names, or `import everything from logging` for all public sibling declarations or folder exports. Imported dependencies are never re-exported implicitly. Names or modules starting with `_` stay private. A sibling module uses its filename without `.aug`; a folder exposes only names listed in `export.aug`. A quoted public repository URL declares a source dependency; `aug run` installs it and locks its commit. Use `aug add URL --as NAME` for a shorter import alias.
 
 ## in
 
@@ -774,7 +774,7 @@ Expand an explicitly imported composition into the application root. Duplicate b
 IndexError implements Error
 ```
 
-Checked failure for an invalid List.get position. Catch it, declare unless IndexError, or use List.at for a nullable lookup.
+Checked failure for an invalid List.get position. Catch it or let it propagate. List.at returns a value or null instead.
 
 ## initialize
 
@@ -782,7 +782,7 @@ Checked failure for an invalid List.get position. Catch it, declare unless Index
 initialize: ...
 ```
 
-Run constructor work once after header inputs and local fields are initialized, before returning the class or record. Put this block inside the declaration, before class methods. Construction stays pure. Records can validate inputs and raise declared unless errors, but cannot replace immutable fields.
+Run constructor work once after header inputs and local fields are initialized, before returning the class or record. Put this block inside the declaration, before class methods. Construction stays pure. Classes declare checked constructor failures with unless before implements; failed construction releases transferred owned fields. Records can infer validation failures but cannot replace immutable fields.
 
 ## input
 
@@ -830,7 +830,7 @@ Define a test case within a when group. Names may be identifiers or quoted descr
 Json
 ```
 
-Immutable JSON data. Parse with august.json, decode concrete records with decode<T>(), and stringify with lossless integer handling.
+Immutable JSON data. Import parse from the JSON source package, decode concrete records with decode<T>(), and stringify with lossless integer handling.
 
 ## List
 
@@ -854,7 +854,7 @@ Grant exclusive mutation of Shared<T> for a short block. Waiting, starting tasks
 [LogRequest(logger=logger)]
 ```
 
-Map a resolve RequestLogger parameter and declare uses logger.complete. Observe the final status and monotonic duration after output finishes, or status 499 on disconnect. Layers complete in reverse written order.
+Map a resolve RequestLogger parameter and infer its complete operation. Observe the final status and monotonic duration after output finishes, or status 499 on disconnect. Layers complete in reverse written order.
 
 ## Map
 
@@ -886,7 +886,7 @@ The missing keyword is rejected. Use null. An omitted optional value and an expl
 Counter(mutable int initial to _count)
 ```
 
-Declare mutable class storage. Header fields are otherwise read-only after construction. An explicit public argument label can initialize private storage with Type label to _field. Mutating methods declare changes self and callers provide mutable access.
+Declare mutable class storage. Header fields are otherwise read-only after construction. An explicit public argument label can initialize private storage with Type label to _field. Bodies infer changes self; callers provide mutable access.
 
 ## next
 
@@ -970,7 +970,7 @@ Bind a required path placeholder by name. A label after the source can select a
 print(value=any) returns void
 ```
 
-Composition and test output. Other callables receive Console and declare uses console.write.
+Write application startup or test output. Other callables receive a Console dependency and call console.write; their bodies infer that capability use.
 
 ## pure
 
@@ -1010,7 +1010,7 @@ Root-only UTF-8 text input. Other callables receive FileReader. Invalid Unicode
 record Point(int x, int y)
 ```
 
-Declare deeply immutable data with labeled construction and structural equality/hashing. Records contain primitives, tuples and other records. An initialize block validates inputs; declare rejected inputs with unless ErrorType.
+Declare deeply immutable data with labeled construction and structural equality/hashing. Records contain primitives, tuples and other records. An initialize block validates inputs; validation infers rejected inputs; an explicit unless ErrorType limits permitted failures.
 
 ## request
 
@@ -1026,7 +1026,7 @@ Receive the immutable raw request when a protocol requires its own binding and e
 [RequireLogin(authentication=auth)]
 ```
 
-Verify credentials before typed body decoding. Map auth to an explicit resolve Authentication parameter and declare uses auth.authenticate. null produces 401; the adapter validates the credential. HTTP policies precede custom parameter interceptors.
+Verify credentials before typed body decoding. Map auth to an explicit resolve Authentication parameter and infer its authenticate operation. null produces 401; the adapter validates the credential. HTTP policies precede custom parameter interceptors.
 
 ## RequirePermission
 
@@ -1044,6 +1044,14 @@ resolve Logger logger; resolve app to program
 
 Declare a dependency in a class or callable header. Callers omit its argument and forward the matching header dependency. Only main and test setup retrieve bindings directly with resolve app to program. Assignment-form resolve is rejected. Scoped dependencies require a scope block.
 
+## resource
+
+```text
+extern C resource Tensor
+```
+
+Declare an opaque native object with a descriptor-checked release operation. Store acquired objects in own bindings; their scope releases them exactly once. Resource declarations belong to native packages, outside main.aug.
+
 ## return
 
 ```text
@@ -1058,7 +1066,7 @@ Finish the current function or method and give its result to the caller. A `void
 name() returns Type
 ```
 
-Specify a function or method return type. Without this clause, the result is `void`; the body may end without `return` or use `return;`. Returning a value requires a declared return type. `returns own Type` transfers ownership to the caller.
+Bodies infer their result from return expressions or their implemented interface when this clause is omitted. No returned value means void. Bodyless signatures still need non-void result types. Explicit result types are checked assertions; returns own Type explicitly transfers ownership. Recursive or ambiguous results may require a type anchor.
 
 ## scope
 
@@ -1170,7 +1178,7 @@ Declare tests beside the class, function, or endpoint. Class suites initialize t
 throw error;
 ```
 
-Raise a value whose class implements `Error`. The enclosing function must declare the error or the call must be handled by a matching `catch`.
+Raise a value whose class implements `Error`. An executable body infers uncaught errors; main must handle them with a matching catch.
 
 ## throws
 
@@ -1223,10 +1231,10 @@ Fixed immutable positions: `(1, 2)` infers Tuple<int, int>, `(1, "apple")` infer
 ## unless
 
 ```text
-load(bool fail) returns string unless FileError
+load(bool fail) unless FileError
 ```
 
-Declare checked failures a function may raise instead of returning its result. Callers must catch the failures or declare them with unless too. Separate several types with `and` or commas; `unless Error` accepts any error type. The statement that raises an error remains `throw`.
+Describe checked failures that escape a call. Bodies infer uncaught errors when unless is omitted; catch blocks remove handled errors. Main must handle escaping errors. Bodyless interfaces declare permitted failures. Explicit unless remains an upper bound; unless Error accepts any error type. Record validation can infer its failures too.
 
 ## unsafe
 
@@ -1239,10 +1247,10 @@ Permit calls to declared `extern C` functions within this block. The compiler do
 ## uses
 
 ```text
-save(resolve FileWriter files, string path) uses files.write unless FileError
+save(resolve FileWriter files, string path)
 ```
 
-Declare the external capability operations this callable may use. Interfaces, public standalone functions, default methods and interceptor around methods keep explicit contracts. Class implementations and private helpers infer uses when omitted; hover, explain and API docs show the result. An explicit uses clause remains an upper bound. Effects are checked through calls and interceptor layers; implementations cannot exceed their interface contract. changes and unless remain explicit, and construction stays pure.
+Bodies infer external capability operations when uses is omitted, including public functions, default methods and interceptor around methods. The editor shows non-editable inline hints; hover, explain, API docs and compiled specs expose checked contracts. Bodyless interfaces and extern declarations keep explicit contracts. An explicit uses clause remains an upper bound. Implementations cannot exceed their interface contract; construction and cleanup stay pure.
 
 ## void
 

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. August builds a native executable when you run a program; the pending 0.21.0 release downloads its own LLVM tools on [supported platforms](../getting-started.md).
+
+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 obtain its pinned LLVM/runtime and package artifacts. Keep the CLI version, supported targets, writable cache paths and complete deployment bundle aligned with the release. Maintainer build images have a separate explicit toolchain. 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