@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/docs/examples/weather-api/main.md

@@ -0,0 +1,65 @@
+---
+title: "main.aug · Weather API"
+generated: true
+source: "examples/weather-api/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Weather API](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`forecasts.aug`](forecasts.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import weatherForecast from forecasts
+serve weatherForecast on port 8787
+```
+
+```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import weatherForecast from forecasts
+serve weatherForecast on port 8787
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+### HTTP configuration
+
+Listen on `127.0.0.1`. Limit request bodies to 1048576 bytes and buffered responses to 4194304 bytes. Serve OpenAPI at `/openapi.json` and API docs at `/docs`.
+
+### Startup
+
+It serves [`weatherForecast`](forecasts.md#symbol-weatherForecast) on port `8787`.
+
+### Dependencies
+
+It uses [`weatherForecast`](forecasts.md#symbol-weatherForecast) from `forecasts`.
+
+::::
+
+:::::

package/docs/examples.json

@@ -2,6 +2,15 @@
   "readme": {
     "stdout": "4\n"
   },
+  "getting-started": {
+    "stdout": "Hello, August!\n",
+    "tests": 1
+  },
+  "wiki-home": {"stdout": "21\n", "tests": 2},
+  "book-functions": {"stdout": "21\n0\n"},
+  "book-data": {"stdout": "21\nQuantity must be positive\nNo name for this identifier\n"},
+  "book-modules": {"stdout": "Hello, August!\n"},
+  "book-state": {"stdout": "4\n", "tests": 2},
   "quickstart": {
     "stdout": "Hello, AugScript!\n"
   },
@@ -40,6 +49,7 @@
   "benchmark-collections": {"stdout":"599970000\ntrue\n"},
   "benchmark-json": {"stdout":"250000\n"},
   "benchmark-http": {"buildOnly":true},
+  "docker-http": {"buildOnly":true, "tests":1},
   "web-guide": {
     "buildOnly": true,
     "tests": 3

package/docs/getting-started.md

@@ -1,5 +1,108 @@
-# Getting started
+---
+prev:
+  text: The August book
+  link: /learn/
+next:
+  text: Values and functions
+  link: /learn/values-and-functions
+---
+
+# Your first project
+
+Build a greeting application, run its test, and read its generated explanation. You will see how an August project starts and how a small module keeps its contract, implementation, and test together.
+
+You need Node.js 24 or later and npm. To run native programs, you also need a C11 compiler on macOS or Linux. On macOS, install Xcode Command Line Tools for Clang; on Linux, install a C toolchain.
+
+You can run the compiler and native libraries in [a VS Code Dev Container](dev-containers.md) instead of installing a host C toolchain. The [Docker guide](docker.md) covers container builds and deployment.
+
+## Create and run the starter
+
+Install August once, then create and run the starter:
 
 ```sh
-npx @greenpandastudios/aug-cli@next init hello-august
+npm install --global @greenpandastudios/aug-cli@next
+aug init hello-august
+cd hello-august
+aug run
 ```
+
+`init` creates a starter, including `AGENTS.md`, and refuses to replace a nonempty destination. npm supplies the CLI and its core I/O library. `aug run` defaults to the current folder: it checks the project, prepares its dependencies, compiles it, and starts it. The starter needs no additional native libraries. It prints:
+
+```text
+Hello, August!
+```
+
+Keep the terminal in `hello-august` for the rest of this chapter. When you later use JSON, tasks, crypto, or HTTP, the first run downloads verified native sources and builds the required libraries in a reusable cache. Setup progress goes to the terminal's error stream so it does not become application output. August reports a missing system tool with an installation step; it does not install system software for you. [Packages and installation](packages.md) covers version pinning, offline runs, and the optional `npx` workflow.
+
+## Read the startup file
+
+The starter's `main.aug` contains its imports, dependency choice, and startup work:
+
+```aug project=getting-started file=main.aug
+import Greeter and SimpleGreeter from greeting
+
+implement Greeter with SimpleGreeter
+resolve Greeter to greeter
+print(value=greeter.greet(name="August"))
+```
+
+`main.aug` is the application entry point. It imports two public declarations from the sibling file `greeting.aug`. `implement` selects the provider for `Greeter`, and `resolve` obtains it as `greeter`. The last line asks for a greeting and prints the result.
+
+The call labels its input `name`. You can read what the string is for without opening the declaration. Labels also let you reorder inputs when a call has several of them.
+
+## Read the module beside it
+
+Open `greeting.aug`. These are the important declarations:
+
+```aug project=getting-started file=greeting.aug
+/** Build a greeting for a named person. */
+interface Greeter:
+    /** Return a greeting for the named person. */
+    greet(string name) returns string
+
+/** A plain-language greeting. */
+SimpleGreeter() implements Greeter:
+    greet(string name):
+        return "Hello, " + name + "!"
+
+test SimpleGreeter greeter:
+    when greetings:
+        greeter = SimpleGreeter()
+        it greets_a_person:
+            assert(greeter.greet(name="August") == "Hello, August!")
+```
+
+The interface is the caller's contract: give `greet` a string named `name`, and receive a string. `SimpleGreeter` implements that contract. Its constructor has no inputs. The method builds a string and returns it.
+
+The test lives beside the class. Its group constructs a greeter, and its case checks an exact result. The comments explain intent and supply editor help. The code describes what happens when the operation runs.
+
+## Change the greeting
+
+In `main.aug`, change `name="August"` to `name="Ada"`. Run:
+
+```sh
+aug check .
+aug run .
+aug test .
+```
+
+The application should print `Hello, Ada!`. The existing test should still pass: it constructs its own subject and checks the greeting for August. Application startup does not run during the test.
+
+Now deliberately change the call's label from `name` to `person`. `check` should fail because `greet` has no input named `person`. Restore `name` and check again. The checker verifies the contract; the test verifies a behavior you chose to exercise.
+
+## Read the generated explanation
+
+```sh
+aug spec .
+aug spec . --check
+```
+
+Open `main.aug.md` and `greeting.aug.md`. They describe the bindings, call, greeting behavior, and test. Their dependency links lead to the used declarations. Generation is deterministic and offline; it does not ask a model to summarize your application.
+
+After an edit, regenerate before committing the explanation. `--check` reports stale files and does not write them. [Compiled specifications](specifications.md) explains the full workflow and its limits.
+
+## Continue with a calculation
+
+You have created, checked, run, tested, and explained an August application. In [Values and functions](learn/values-and-functions.md), you will write a calculation without an injected dependency and learn how labeled shorthand and conditions read.
+
+For a service, try [the weather API starter](weather-api.md). You can also [browse complete projects](examples/index.md) with code and actual compiled specs beside each other. The gallery's Indentation and Braces controls display the same checked program in either block style.

package/docs/grammar.md

@@ -1,6 +1,6 @@
 # Grammar and line boundaries
 
-This is the compact accepted grammar for 0.19. `Name` is an identifier, and bracketed grammar groups below are optional. These text blocks describe syntax rather than executable snippets.
+This is the compact accepted grammar for 0.20. `Name` is an identifier, and bracketed grammar groups below are optional. These text blocks describe syntax rather than executable snippets.
 
 ## Blocks and declarations
 
@@ -26,12 +26,12 @@ Interface   := ("interface" | "capability") Name [Generics]
 Interceptor := "interceptor" Name [Generics] ["(" ResolveFields ")"] Block
 Composition := "composition" Name BlockOfBindings
 Endpoint    := [Tags] "endpoint" HttpMethod String "as" Name "(" Parameters ")"
-               ("returns" Type | "streams" Type) ["uses" Paths]
+               ["returns" Type | "streams" Type] ["uses" Paths]
                ["unless" Type ["with status" Integer] {"and" Type ["with status" Integer]}]
                ["with status" Integer] Block
 ```
 
-An interface/class/interceptor block contains method declarations. A record ends after its header or validation block and has no behavior body. A function's absent returns clause means void. Its body is required for calls, except extern C. There is no class or function prefix.
+An interface/class/interceptor block contains method declarations. A record ends after its header or validation block and has no behavior body. An executable body infers an absent returns clause; no returned value means void. A bodyless signature defaults to void. Omitted changes, uses, and unless clauses are inferred from executable bodies; explicit clauses remain checked bounds. Its body is required for calls, except extern C. There is no class or function prefix.
 
 The implements clause identifies a class. Its initialize block appears inside the class before methods, and runs after field initialization. Records can contain one initialize block for validation. Nested function declarations are not supported. A root `counter()` statement is a call, not a declaration.
 
@@ -53,7 +53,7 @@ Variance is accepted only on interfaces; mutable storage applies to class header
 ## Imports, bindings, and calls
 
 ```text
-Import      := "import" (Name {"and" Name} | "everything") "from" DottedPath End
+Import      := "import" (Name {"and" Name} | "everything") "from" (DottedPath | RepositoryUrl {"." Name}) End
 Export      := "export" Name "from" SiblingName End
              | "export" "folder" ChildName End
 Binding     := "implement" Key ["<" Types ">"] "with" Type
@@ -64,6 +64,8 @@ Assignment  := [["own" | "borrow"] Type] Target ("=" | "to") Expression End
 Resolve     := "resolve" Key ["<" Types ">"] "to" Name End
 ```
 
+A quoted public repository URL declares a source dependency. A URL can select a tag or commit with #REVISION. See [packages](packages.md) for aliases and commit locks.
+
 The formatter uses implement/with and resolve/to, and preserves wildcard imports. Assignment style remains a project preference. Repeated paths/errors can use and or comma; canonical error clauses use and. Collection constructor elements are positional because their order carries meaning. Assert also accepts its single bool positionally.
 
 ## Control flow and tests

package/docs/guides/change-a-module.md

@@ -0,0 +1,64 @@
+# Change an unfamiliar module
+
+A change request is easier to review when you can trace its inputs, dependencies, and observable behavior. This guide follows the repository's tested calculator application. It uses the same process for a human developer and a coding agent; the checks establish specific program properties, while you still review whether the change meets the request.
+
+## Establish a working baseline
+
+Download [the tested calculator project](../examples/developer-workflow/index.md#try-this-project), extract it, and prepare [the native dependencies](../packages.md#npm-registry). From the folder containing the extracted project:
+
+```sh
+cd developer-workflow
+npx @greenpandastudios/aug-cli@next check .
+npx @greenpandastudios/aug-cli@next test .
+npx @greenpandastudios/aug-cli@next spec .
+```
+
+Open [the application's entry point](../examples/developer-workflow/main.md). It selects the console and logger, constructs the calculator, and calls its addition operation. Then open [the calculator and its compiled spec](../examples/developer-workflow/calculator.md). Its interface describes addition and console output. The class receives a logger. The tests supply a private silent logger and check the returned sums.
+
+The private test adapter implements the public logging contract. It keeps these cases independent of console messages. Test setup chooses its own providers; application startup does not run during a case.
+
+## Trace only what the change needs
+
+Suppose the request is: **also verify addition with a negative operand**. Read the `Arithmetic.add` contract, `Calculator.add`, and the `addition` test group. Follow [the logging contract](../examples/developer-workflow/logging/logger.md) if you need to understand its effect. The dependency section of the compiled spec links to the used surfaces; it does not repeat every dependency implementation.
+
+For a bounded context report:
+
+```sh
+npx @greenpandastudios/aug-cli@next explain . --file calculator.aug --name Calculator
+npx @greenpandastudios/aug-cli@next context . --file calculator.aug --name Calculator --budget 6000
+```
+
+The report gives checked contracts and related context. It helps you choose which files to read; it does not establish that the requested behavior is correct. A bounded result can be truncated. Check its `truncated` flag and increase the budget or follow the source links when the required contract is absent.
+
+## Make and check the change
+
+Add a case to the existing `addition` group. The following is a fragment, not a standalone file:
+
+```text
+it "adds a negative operand" {
+    assert(calculator.add(left=-2, right=5) == 3)
+}
+```
+
+The existing group setup supplies the calculator and its dependencies. Run `check` and `test` again. The new case should pass without changing the implementation: the current operation already adds integers. If your change needs a new error, dependency, or mutation, update the public contract and its callers deliberately; those decisions belong in the review.
+
+## Review the explanation with the patch
+
+Regenerate specs after the change:
+
+```sh
+npx @greenpandastudios/aug-cli@next spec .
+npx @greenpandastudios/aug-cli@next spec . --check
+```
+
+Compare the edited files with the originals, using your editor or source control. The source change adds a behavior case. The spec change should describe that case. Review both and confirm that neither adds an unexpected public export, effect, or dependency. Generated explanations describe checked source; handwritten comments explain domain intent. A passing test covers its exercised inputs, and a current spec is still subject to reader review.
+
+## Give a coding agent the same starting point
+
+A useful instruction is:
+
+> Read `calculator.aug.md` first and follow its linked contracts. Inspect the August source and tests before editing. Add a case that verifies addition with a negative operand. Run `aug check` and `aug test`, regenerate with `aug spec`, and review the source and spec diffs. Report the checks that passed and any limits.
+
+Give the agent an explicit instruction to use the neighboring spec and verify its work. This workflow demonstrates the tools; it makes no comparative productivity claim.
+
+For a larger boundary example, explore [modules and composition](../examples/approved-design/index.md). For a different task, return to the [guides](index.md).

package/docs/guides/index.md

@@ -0,0 +1,27 @@
+# Guides
+
+Choose a guide for the task you are doing. If you are learning August for the first time, start with [the book](../learn/index.md); it introduces the language in order.
+
+## Understand and change a project
+
+| Task | Guide |
+| --- | --- |
+| Review unfamiliar code or an agent's change | [Change a module](change-a-module.md) |
+| Generate and check the neighboring explanations | [Compiled specifications](../specifications.md) |
+| Verify behavior and substitute test dependencies | [Unit tests](../testing.md) |
+| Inspect a diagnostic or find a fix | [Diagnostics](../diagnostics.md) |
+| Use completion, navigation, context, or native builds | [VS Code](../editor.md) and [CLI](../tooling.md) |
+
+## Build and distribute an application
+
+| Task | Guide |
+| --- | --- |
+| Build your first HTTP service | [Weather API](../weather-api.md) |
+| Add endpoints, pages, streams, or crypto | [Web applications](../web.md) |
+| Create or consume a source library | [Packages](../packages.md#author-a-package) |
+| Build and deploy a Linux application image | [Docker](../docker.md) |
+| Edit, run, and test inside a container | [VS Code Dev Containers](../dev-containers.md) |
+| Measure execution time or HTTP throughput | [Performance](../performance.md) |
+| Assess a trial deployment | [Production readiness](../production-readiness.md) |
+
+For exact syntax and contracts, consult the [language reference](../reference.md) and library API pages. [Complete projects](../examples/index.md) show the files, formatted source, and compiled specs together.

package/docs/index.md

@@ -3,44 +3,66 @@ layout: home
 hero:
   name: August
   text: The world runs on language
-  tagline: A statically checked language for developers working with LLMs. Readable modules, clear dependencies, explicit effects, native C output.
+  tagline: A programming language for understanding and changing code together—with teammates and coding agents.
   actions:
     - theme: brand
-      text: Build your first project
-      link: /getting-started
+      text: Learn August
+      link: /learn/
     - theme: alt
-      text: Install and try it
-      link: /packages
-    - theme: alt
-      text: Build a web service
-      link: /web
-    - theme: alt
-      text: Browse real projects
-      link: /examples/
-    - theme: alt
-      text: See performance graphs
-      link: /performance
-features:
-  - title: Understand a module in context
-    details: Public exports, labeled inputs, same-file tests, and source comments tell a new reader what the code promises.
-  - title: See dependencies and side effects
-    details: Interface contracts, resolve parameters, and changes clauses keep behavior visible at the module boundary. Implementation effects are inferred and explained in hover and specs.
-  - title: Build native applications
-    details: The CLI checks August, emits C11, and invokes the C compiler. First-party HTTP endpoints use narrow native library adapters.
+      text: Read a real project
+      link: /examples/hello/
 ---
 
-## Documentation for the code you run
+## Understand the change before you make it
+
+A new teammate opens a module. A coding agent receives a change request. Both need to know what the module does, which dependencies it uses, and what a change could affect.
+
+August puts that information close to the code. Calls name their inputs. Modules expose a deliberate public surface. Interfaces describe behavior and effects. Tests live beside the declarations they check. The compiler can turn each source file into a linked, readable specification.
+
+Here is a complete application. Save these two files in the same folder:
+
+**main.aug**
+
+```aug project=wiki-home file=main.aug
+import total from prices
+
+print(value=total(price=7, quantity=3))
+```
+
+**prices.aug**
+
+```aug project=wiki-home file=prices.aug
+total(int price, int quantity) returns int:
+    if quantity > 0:
+        return price * quantity
+    return 0
+
+test total:
+    when quantities:
+        it calculates_a_total:
+            assert(total(price=7, quantity=3) == 21)
+        it treats_zero_as_empty:
+            assert(total(price=7, quantity=0) == 0)
+```
+
+`aug run .` prints `21`. `aug test .` runs the two cases. `aug spec .` generates an explanation of `total`:
+
+> It takes `price` and `quantity` as integers. It returns `price` times `quantity` if `quantity` is positive, or `0` otherwise.
+
+The explanation is generated from checked code, offline and deterministically. It links to the dependencies the file uses. Comments can supply the intent that code alone cannot express. [See code and its actual compiled specification](examples/hello/app/greeter.md), or follow [a review of an unfamiliar module](guides/change-a-module.md).
+
+## Learn it, then look things up
 
-These pages are versioned with the compiler. Guide projects are compiled and tested in CI. Library API pages and language construct help are generated from the same declarations and comments that supply editor hover. [Compiled specifications](specifications.md) explain each source file beside its code, including private behavior and links to offline dependency docs.
+The [August book](learn/index.md) assumes you already program in another language. It starts with installation and a running application, then introduces values, errors, modules, dependencies, and mutable state. Each chapter gives you a program to run and something to change.
 
-Start with [getting started](getting-started.md) to create a new project with one `npx` command. [Browse complete projects](examples/index.md) with a choice of indentation or braces and compiled specifications beside the code. The [same-app OpenID Connect example](examples/oidc-login/index.md) demonstrates a login page, provider, client, and separate session JWT.
+For a specific task, use the [guides](guides/index.md). For a syntax rule or API, use the [language reference](reference.md) and [library reference](api/io.md). The [project gallery](examples/index.md) shows complete applications with code and specifications side by side; you can switch between indentation and braces.
 
-## Why August
+## Native programs, measured openly
 
-A developer opening an unfamiliar file should see what it provides, what it imports, which inputs each call takes, what it can change, and which errors it can raise. August puts tests beside declarations and generates a readable specification from checked code. Folder exports form a deliberate public boundary. These choices help people and code assistants work within small, explainable modules.
+August checks source, generates C11, and invokes a C compiler to build a native executable. The [performance page](performance.md) publishes the programs, graphs, raw samples, environment, and reproduction commands. Its results describe those workloads on that host. Measure your own application's work before making a performance decision.
 
-## Performance and readiness
+## A public preview
 
-August emits C11 and builds native executables. In the [published benchmark suite](performance.md), the CPU loop took 7.24 ms in August and 8.17 ms in C on the measured host; a 200,000-item Map/Set workload took 15.10 ms in August and 6.38 ms in C. The HTTP result depends on load; at 16 clients the measured August server handled 73,370 requests per second, while at other client counts the comparison changes. See the graphs, code, inputs, hardware, and reproduction commands before drawing conclusions.
+August is experimental and has not reached 1.0. Syntax and package compatibility can change. Tasks currently run cooperatively on one OS thread. HTTP and crypto libraries have working examples and documented operational gaps; the login example is a development demonstration.
 
-August is experimental. [Production readiness](production-readiness.md) identifies platform, licensing, security, and reliability gates. The [roadmap to 1.0.0](roadmap.md) and [gap ledger](web-library-gaps.md) show the work still required. See [packages](packages.md) for installation and the [Docker images](docker.md) for Linux core, web, and crypto applications.
+Read [what August is designed for](about.md), [production readiness](production-readiness.md), and the [roadmap to 1.0](roadmap.md) before choosing it for a deployment. Installation options are maintained on the [packages page](packages.md). Source and issues are on [GitHub](https://github.com/GreenPandaStudios/augscript); the language repository is MIT licensed, and native dependencies have [their own terms](production-readiness.md#dependencies-and-licenses).

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
 

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. Records can validate inputs and raise checked errors, 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
 
@@ -1058,7 +1058,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 +1170,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 +1223,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 +1239,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