@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/examples/approved-design/domain/numbers.aug.md

@@ -1,141 +1,44 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `numbers.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`RangeError`](numbers.aug.md#symbol-RangeError) is a class implementing `Error`.
-- [`Positive`](numbers.aug.md#symbol-Positive) is an interceptor.
-- [`double`](numbers.aug.md#symbol-double) is a function returning `int`.
-- [`test double`](numbers.aug.md#symbol-test%20double) is a same-file test suite.
+# `numbers.aug`
 
 <a id="symbol-RangeError"></a>
+## `RangeError` · class · [source](numbers.aug#L3)
 
-## `RangeError`
-
-[source](numbers.aug#L2)
-
-Behavioral class.
-
-Satisfies `Error`.
-
-**Author documentation**
-
-Raised when an input is outside the operation's domain.
-
-**Inputs**
-
-- `value` (`int`) — required labeled input — stored as `value` and read-only after initialization.
+Raised when an input is outside the operation's domain. It implements `Error`. It takes `value` as an integer, kept read-only.
 
 <a id="symbol-Positive"></a>
+## `Positive` · interceptor · [source](numbers.aug#L6)
 
-## `Positive`
-
-[source](numbers.aug#L5)
-
-Function or constructor middleware.
-
-Type parameters: `T`.
-
-**Author documentation**
-
-A pure validation layer, shared by any compatible callable.
-
-Create a fresh interceptor for each invocation. Its around operation can delegate once, change selected inputs, or short-circuit with a compatible result or failure.
+A pure validation layer, shared by any compatible callable. The type parameters are `T`. Creates one interceptor per invocation. Its around operation may delegate once or finish early.
 
 <a id="symbol-Positive.around"></a>
+### `Positive.around` · [source](numbers.aug#L7)
 
-### `Positive.around`
-
-[source](numbers.aug#L6)
-
-**Inputs**
-
-- `amount` (`int`) — required labeled input.
-
-Returns: `T`.
-
-Can fail with `RangeError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- If `amount` is less than `0`:
-  - Fail with call [`RangeError`](numbers.aug.md#symbol-RangeError) with `value` = `amount`. Transfer control to a matching catch or propagate the failure.
-- Return call `next`.
+It takes `amount` as an integer. Failures can raise [`RangeError`](numbers.aug.md#symbol-RangeError). If `amount` is negative, it raises a [`RangeError`](numbers.aug.md#symbol-RangeError) with `value` from `amount`. It returns `next`.
 
 <a id="symbol-double"></a>
+## `double` · [source](numbers.aug#L18)
 
-## `double`
+Double a nonnegative amount. It takes `amount` as an integer (Integer to double). It returns `int` — Twice the amount, with defined integer wrapping. Failures can raise [`RangeError`](numbers.aug.md#symbol-RangeError) (A validation layer rejected a negative input).
 
-[source](numbers.aug#L17)
-
-**Inputs**
-
-- `amount` (`int`) — required labeled input.
-
-Returns: `int`.
-
-Can fail with `RangeError`. Callers must catch or propagate these errors.
-
-**Interceptors, in execution order**
-
-1. Call [`Positive.around`](numbers.aug.md#symbol-Positive.around). It can call the next layer or finish with its own result or failure. Unselected inputs pass through.
-
-The first layer wraps the remaining layers. HTTP policies run before wire decoding; custom interceptors run after decoding. Follow linked behavior to see its conditions, input changes, and calls to the next layer.
-
-**What it does**
-
-- Return `amount` times `2`.
-
-**Author documentation**
-
-Double a nonnegative amount.
-
-**Returns** Twice the amount, with defined integer wrapping.
-
-**Parameters**
-- `amount`: Integer to double.
-
-**Throws**
-- `RangeError`: A validation layer rejected a negative input.
+Layers run in the declared order. Call [`Positive.around`](numbers.aug.md#symbol-Positive.around). It returns `amount` times `2`.
 
 <a id="symbol-test double"></a>
+## `test double` · [source](numbers.aug#L20)
 
-## `test double`
-
-[source](numbers.aug#L19)
-
-Same-file function tests for [`double`](numbers.aug.md#symbol-double). Each case gets isolated setup and dependency bindings.
-
-### Group `positive`
-
-#### `doubles`
-
-[source](numbers.aug#L21)
-
-Run once for each row of a tuple containing `0`, `0`; a tuple containing `3`, `6`; a tuple containing `7`, `14`. Bind row positions to `input`, `expected`.
-
-- Call `assert` with (call [`double`](numbers.aug.md#symbol-double) with `amount` = `input` equals `expected`).
-
-#### `rejects_negative`
+Tests [`double`](numbers.aug.md#symbol-double). Each case gets fresh setup and dependencies.
 
-[source](numbers.aug#L23)
+### `positive`
 
-- Set `rejected` of type `bool` to `false`.
-- Try these operations:
-  - Call [`double`](numbers.aug.md#symbol-double) with `amount` = `-1`.
-- If they fail with [`RangeError`](numbers.aug.md#symbol-RangeError), name the failure `error` and recover:
-  - Set `rejected` to `value` of `error` equals `-1`.
-- Call `assert` with `rejected` = `rejected`.
+#### `doubles` · [source](numbers.aug#L22)
 
-## Built-in operations used by this file
+Run once for each row of a tuple containing `0`, `0`; a tuple containing `3`, `6`; a tuple containing `7`, `14`. Bind row positions to `input`, `expected`. The test requires [`double`](numbers.aug.md#symbol-double) with `amount` from `input` equals `expected`.
 
-- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
+#### `rejects_negative` · [source](numbers.aug#L24)
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+It sets `rejected` to `false`.
 
-## Shared language rules
+It tries to call [`double`](numbers.aug.md#symbol-double) with `amount` `-1`. If this work raises [`RangeError`](numbers.aug.md#symbol-RangeError) as `error`, it sets `rejected` to `error.value` equals `-1`. The test requires `rejected` is true.
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/approved-design/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 import Application and ApplicationImpl and Fruit and double and RangeError from domain
 import Counter and Counters from counters

package/examples/approved-design/main.aug.md

@@ -1,108 +1,25 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Providers
 
-## In this file
+`Console` is provided by [`SystemConsole`](.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-SystemConsole). The same instance is shared.
 
-- Include providers from `Counters`.
-- Register 2 dependency providers before startup.
-- Run startup operations with checked error recovery.
-- Run 7 other startup steps in source order.
+`Application` is provided by [`ApplicationImpl`](domain/app.aug.md#symbol-ApplicationImpl). The same instance is shared. It requires bindings for `Console`. Include providers from [`Counters`](counters.aug.md#symbol-Counters).
 
-## Dependency providers
+## Startup
 
-Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+It sets `app` to the instance provided for `Application`. It calls [`app.start`](domain/app.aug.md#symbol-Application.start). It sets `names` to a map with `1` mapped to `"apple"`; `2` mapped to `"pear"`. If the value under `2` in `names` is null, it prints `"missing fruit"`.
 
-- Provide [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole) when `Console` is requested. Reuse one instance.
-- Provide [`ApplicationImpl`](domain/app.aug.md#symbol-ApplicationImpl) when `Application` is requested. Reuse one instance. Required dependencies: `Console`.
-- Include the providers from [`Counters`](counters.aug.md#symbol-Counters) before execution.
+If the value under `2` in `names` is not null, using `name` for it prints `name`. It splits a tuple containing `3`, `"plum"` into `code` and `label` in order. It prints the number of elements in a set containing a [`Fruit`](domain/models.aug.md#symbol-Fruit) with `code` and `name` from `label`, a [`Fruit`](domain/models.aug.md#symbol-Fruit) with `name` from `label` and `code`. Within a task and ownership scope, it sets `counter` to the instance provided for `Counter`.
 
-## Startup, in source order
+With temporary permission to change `counter`, it calls [`counter.increment`](counters.aug.md#symbol-Counter.increment). It prints [`counter.value`](counters.aug.md#symbol-Counter.value). On leaving this scope, join its child tasks and release its local values. It prints [`double`](domain/numbers.aug.md#symbol-double) with `amount` `7`.
 
-- Set `app` to the instance provided for `Application`.
-- Call [`Application.start`](domain/app.aug.md#symbol-Application.start) on `app`.
-- Set `names` to a map with `1` mapped to `"apple"`; `2` mapped to `"pear"`.
-- Select the matching case for call `get` on `names` with `key` = `2`:
-  - A null value, including omitted optional input:
-    - Call `print` with `value` = `"missing fruit"`.
-  - A present, non-null value, named `name`:
-    - Call `print` with `value` = `name`.
-- Split a tuple containing `3`, `"plum"` into `code`, `label`, in that order.
-- Call `print` with `value` = call `length` on a set containing call [`Fruit`](domain/models.aug.md#symbol-Fruit) with `code` = `code`; `name` = `label`, call [`Fruit`](domain/models.aug.md#symbol-Fruit) with `name` = `label`; `code` = `code`.
-- Create a dependency and task scope. Join its child tasks and release scoped values before leaving:
-  - Set `counter` to the instance provided for `Counter`.
-  - Grant exclusive mutable access to `counter` for this block, then end the borrow:
-    - Call [`Counter.increment`](counters.aug.md#symbol-Counter.increment) on `counter`.
-  - Call `print` with `value` = call [`Counter.value`](counters.aug.md#symbol-Counter.value) on `counter`.
-- Try these operations:
-  - Call `print` with `value` = call [`double`](domain/numbers.aug.md#symbol-double) with `amount` = `7`.
-  - Call [`double`](domain/numbers.aug.md#symbol-double) with `amount` = `-1`.
-- If they fail with [`RangeError`](domain/numbers.aug.md#symbol-RangeError), name the failure `error` and recover:
-  - Call `print` with `value` = `"negative amount rejected"`.
+It calls [`double`](domain/numbers.aug.md#symbol-double) with `amount` `-1`. If this work raises [`RangeError`](domain/numbers.aug.md#symbol-RangeError), it prints `"negative amount rejected"`.
 
-## Dependencies used by this file
+## Dependencies
 
-Only referenced types and operations appear here. Each name links to its complete specification.
+It uses [`SystemConsole`](.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-SystemConsole) from `august.io`. It uses [`Counter`](counters.aug.md#symbol-Counter) ([`increment`](counters.aug.md#symbol-Counter.increment) and [`value`](counters.aug.md#symbol-Counter.value)) and [`Counters`](counters.aug.md#symbol-Counters) from `counters`. It uses [`Application`](domain/app.aug.md#symbol-Application) ([`start`](domain/app.aug.md#symbol-Application.start)), [`ApplicationImpl`](domain/app.aug.md#symbol-ApplicationImpl), [`Fruit`](domain/models.aug.md#symbol-Fruit), [`RangeError`](domain/numbers.aug.md#symbol-RangeError), and [`double`](domain/numbers.aug.md#symbol-double) from `domain`.
 
-### [`SystemConsole`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-SystemConsole)
-
-Class from `august.io`.
-
-Used as a type or provider.
-
-### [`Counter`](counters.aug.md#symbol-Counter)
-
-Interface from `counters`.
-
-- [`Counter.increment`](counters.aug.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
-- [`Counter.value`](counters.aug.md#symbol-Counter.value) (no caller inputs) → `int`.
-
-### [`Counters`](counters.aug.md#symbol-Counters)
-
-Composition from `counters`.
-
-Used as a type or provider.
-
-### [`Application`](domain/app.aug.md#symbol-Application)
-
-Interface from `domain`.
-
-- [`Application.start`](domain/app.aug.md#symbol-Application.start) (no caller inputs) → `void`; uses [`Console.write`](.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-### [`ApplicationImpl`](domain/app.aug.md#symbol-ApplicationImpl)
-
-Class from `domain`.
-
-Used as a type or provider.
-
-### [`Fruit`](domain/models.aug.md#symbol-Fruit)
-
-Record from `domain`.
-
-- Construct with `code`: `int`, `name`: `string` → [`Fruit`](domain/models.aug.md#symbol-Fruit).
-
-### [`RangeError`](domain/numbers.aug.md#symbol-RangeError)
-
-Class from `domain`.
-
-Used as a type or provider.
-
-### [`double`](domain/numbers.aug.md#symbol-double)
-
-Function from `domain`.
-
-- [`double`](domain/numbers.aug.md#symbol-double) (`amount`: `int`) → `int`; can fail with `RangeError`.
-
-## Built-in operations used by this file
-
-- `Map<int, string>.get` (`key`: `int`) → `optional string`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
-- `Set<Fruit>.length` (no inputs) → `int`: Read the number of elements.
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/benchmark/.aug-spec/manifest.json

@@ -3,5 +3,5 @@
   "files": [
     "main.aug.md"
   ],
-  "digest": "4179cb6d189b3c491e75fa38ee2d1c982f6c3b8fc83309e923606b2a51e4ad45"
+  "digest": "412b3faf59d5e652499476813673a7e77384589c05b0f147c6fc1eb708111174"
 }

package/examples/benchmark/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 // A deterministic native workload: arithmetic and 20,000 hash entries.
 own Map<int,int> values = {}
 own Set<int> unique = {}

package/examples/benchmark/main.aug.md

@@ -1,43 +1,13 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Startup
 
-## In this file
+It sets `values` of type `Map<int,int>` to a context-typed empty collection with no items. `values` of type `Map<int,int>` owns this value. It sets `unique` of type `Set<int>` to a context-typed empty collection with no items. `unique` of type `Set<int>` owns this value.
 
-- Run 8 other startup steps in source order.
+It sets `index` to `0`. While `index` is less than `20000`, it stores `index` times `3` in `values` under `index`; then it adds `index` to `unique`; then it increases `index` by `1`. After the loop, it sets `checksum` to `0`. For each `key` and `value` in a snapshot of `values`, if whether `unique` contains `key` returns true, it increases `checksum` by `value`.
 
-## Startup, in source order
+After the loop, it prints `checksum`. It prints the number of elements in `values` equals the number of elements in `unique`.
 
-- Set `values` of type `Map<int,int>` to a context-typed empty collection with no items.
-- This variable owns the value.
-- Set `unique` of type `Set<int>` to a context-typed empty collection with no items.
-- This variable owns the value.
-- Set `index` of type `int` to `0`.
-- While `index` is less than `20000`, repeat:
-  - Call `set` on `values` with `key` = `index`; `value` = (`index` times `3`).
-  - Call `add` on `unique` with `value` = `index`.
-  - Set `index` to `index` plus `1`.
-  - Check the condition again before the next iteration.
-- Set `checksum` of type `int` to `0`.
-- For each `key` and `value` in a snapshot of `values`, in iteration order:
-  - If call `contains` on `unique` with `value` = `key` is true:
-    - Set `checksum` to `checksum` plus `value`.
-- Call `print` with `value` = `checksum`.
-- Call `print` with `value` = (call `length` on `values` equals call `length` on `unique`).
-
-## Built-in operations used by this file
-
-- `Map<int, int>.length` (no inputs) → `int`: Read the number of elements.
-- `Map<int, int>.set` (`key`: `int`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
-- `Set<int>.add` (`value`: `int`) → `void`: Insert a unique element with exclusive mutable access. Changes the receiver.
-- `Set<int>.contains` (`value`: `int`) → `bool`: Test structural or identity equality with a stored element.
-- `Set<int>.length` (no inputs) → `int`: Read the number of elements.
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/cli-args/.aug-spec/manifest.json

@@ -3,5 +3,5 @@
   "files": [
     "main.aug.md"
   ],
-  "digest": "436feb0daa7b3ed51ce239af6888c680ef6e692c6e5d6f00503a32bc5869d03d"
+  "digest": "1a3c66590ddd596ccdd9f0a99c7dfc1613a42f7ac533b128de7690d375f3ab44"
 }

package/examples/cli-args/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 try {
     args = arguments()
     print(value=args.length())

package/examples/cli-args/main.aug.md

@@ -1,38 +1,11 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Startup
 
-## In this file
+It sets `args` to `arguments`. It prints the number of elements in `args`. If the number of elements in `args` is positive, it prints the item at index `0` in `args`. It sets `numbers` to a list of `int` containing `1`, `2`.
 
-- Run startup operations with checked error recovery.
+With temporary permission to change `numbers`, it appends `3` to `numbers`. It prints the item at index `2` in `numbers`. If this work raises `IndexError`, it prints `"unexpected index failure"`.
 
-## Startup, in source order
-
-- Try these operations:
-  - Set `args` to call `arguments`.
-  - Call `print` with `value` = call `length` on `args`.
-  - If call `length` on `args` is greater than `0`:
-    - Call `print` with `value` = call `get` on `args` with `index` = `0`.
-  - Set `numbers` to a list of `int` containing `1`, `2`.
-  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
-    - Call `append` on `numbers` with `value` = `3`.
-  - Call `print` with `value` = call `get` on `numbers` with `index` = `2`.
-- If they fail with `IndexError`, name the failure `error` and recover:
-  - Call `print` with `value` = `"unexpected index failure"`.
-
-## Built-in operations used by this file
-
-- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
-- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<string>.get` (`index`: `int`) → `string`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<string>.length` (no inputs) → `int`: Read the number of elements.
-- `arguments` (no inputs) → `List<string>`: Composition arguments. Other callables receive the Arguments capability.
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/collections/.aug-spec/manifest.json

@@ -3,5 +3,5 @@
   "files": [
     "main.aug.md"
   ],
-  "digest": "8acdc38ecfcc6e5eb277e44abe6700f536bc46235bafbeb0a3c5e7dcdfd21624"
+  "digest": "ca7a12310d1b073bb24ae40f3efde891b07dc464453bb40a7304dfb3e0ba8fe9"
 }

package/examples/collections/main.aug

@@ -1,3 +1,4 @@
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 try {
     numbers = List<int>(2, 4)
     borrow numbers {

package/examples/collections/main.aug.md

@@ -1,43 +1,13 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `main.aug` specification
+# `main.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Startup
 
-## In this file
+It sets `numbers` to a list of `int` containing `2`, `4`. With temporary permission to change `numbers`, it appends `6` to `numbers`. It prints the number of elements in `numbers`. It prints the item at index `1` in `numbers`.
 
-- Run startup operations with checked error recovery.
+It sets `scores` to an empty map from `string` to `int`. With temporary permission to change `scores`, it stores `42` in `scores` under `"ada"`. It prints whether `scores` contains the key `"ada"`. It prints the value under `"ada"` in `scores`.
 
-## Startup, in source order
+It prints the number of elements in `scores`. If this work raises `IndexError`, it prints `"unexpected index failure"`.
 
-- Try these operations:
-  - Set `numbers` to a list of `int` containing `2`, `4`.
-  - Grant exclusive mutable access to `numbers` for this block, then end the borrow:
-    - Call `append` on `numbers` with `value` = `6`.
-  - Call `print` with `value` = call `length` on `numbers`.
-  - Call `print` with `value` = call `get` on `numbers` with `index` = `1`.
-  - Set `scores` to an empty map from `string` to `int`.
-  - Grant exclusive mutable access to `scores` for this block, then end the borrow:
-    - Call `set` on `scores` with `value` = `42`; `key` = `"ada"`.
-  - Call `print` with `value` = call `contains` on `scores` with `key` = `"ada"`.
-  - Call `print` with `value` = call `get` on `scores` with `key` = `"ada"`.
-  - Call `print` with `value` = call `length` on `scores`.
-- If they fail with `IndexError`, name the failure `error` and recover:
-  - Call `print` with `value` = `"unexpected index failure"`.
-
-## Built-in operations used by this file
-
-- `List<int>.append` (`value`: `int`) → `void`: Append an element with exclusive mutable access. Read-only and owned aliases cannot be stored here. Changes the receiver.
-- `List<int>.get` (`index`: `int`) → `int`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<int>.length` (no inputs) → `int`: Read the number of elements.
-- `Map<string, int>.contains` (`key`: `string`) → `bool`: Check for a key, including entries whose value is null.
-- `Map<string, int>.get` (`key`: `string`) → `optional int`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
-- `Map<string, int>.length` (no inputs) → `int`: Read the number of elements.
-- `Map<string, int>.set` (`key`: `string`, `value`: `int`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
-- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
-
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/{generic-di/.aug-spec/august/0.19.0 → developer-workflow/.aug-spec/august/0.21.0}/io/contracts.aug

@@ -1,4 +1,5 @@
 // Generated by aug spec. This is a copy of the installed dependency source.
+// aug-spec: "contracts.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Permission to write to a console, provided by an explicitly selected adapter. */
 capability Console:
     /** Write one line of text. @param value Text to display. */
@@ -21,9 +22,9 @@ capability FileWriter:
 
 /** Native files. Operations are explicit; construction opens no files. */
 LocalFiles() implements FileReader, FileWriter:
-    read(string path) returns string unless FileError:
+    read(string path) :
         return read_file(path=path)
-    write(string path, string content) unless FileError:
+    write(string path, string content) :
         write_file(path=path, content=content)
 
 /** Read command-line input through an explicit dependency. */
@@ -32,5 +33,5 @@ capability Arguments:
 
 /** Native command-line arguments. */
 ProcessArguments() implements Arguments:
-    read() returns List<string>:
+    read() :
         return arguments()

package/examples/developer-workflow/.aug-spec/august/0.21.0/io/contracts.aug.md

@@ -0,0 +1,82 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug`
+
+<a id="symbol-Console"></a>
+## `Console` · capability interface · [source](contracts.aug#L4)
+
+Permission to write to a console, provided by an explicitly selected adapter.
+
+<a id="symbol-Console.write"></a>
+### `Console.write` · [source](contracts.aug#L6)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It can call [`Console.write`](contracts.aug.md#symbol-Console.write).
+
+<a id="symbol-SystemConsole"></a>
+## `SystemConsole` · class · [source](contracts.aug#L9)
+
+The native standard-output adapter. Construction performs no output. It implements [`Console`](contracts.aug.md#symbol-Console).
+
+<a id="symbol-SystemConsole.write"></a>
+### `SystemConsole.write` · [source](contracts.aug#L10)
+
+Write one line of text. The type parameters are `T`. It takes `value` as `T` (Text to display). It prints `value`.
+
+<a id="symbol-FileReader"></a>
+## `FileReader` · capability interface · [source](contracts.aug#L14)
+
+Read UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileReader.read"></a>
+### `FileReader.read` · [source](contracts.aug#L16)
+
+Read text. It takes `path` as a string (File path).
+
+It returns `string`. It can call [`FileReader.read`](contracts.aug.md#symbol-FileReader.read). Failures can raise `FileError` (The file could not be read).
+
+<a id="symbol-FileWriter"></a>
+## `FileWriter` · capability interface · [source](contracts.aug#L19)
+
+Write UTF-8 text through an explicitly selected filesystem adapter.
+
+<a id="symbol-FileWriter.write"></a>
+### `FileWriter.write` · [source](contracts.aug#L21)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). It can call [`FileWriter.write`](contracts.aug.md#symbol-FileWriter.write). Failures can raise `FileError` (Writing failed).
+
+<a id="symbol-LocalFiles"></a>
+## `LocalFiles` · class · [source](contracts.aug#L24)
+
+Native files. Operations are explicit; construction opens no files. It implements [`FileReader`](contracts.aug.md#symbol-FileReader) and [`FileWriter`](contracts.aug.md#symbol-FileWriter).
+
+<a id="symbol-LocalFiles.read"></a>
+### `LocalFiles.read` · [source](contracts.aug#L25)
+
+Read text. It takes `path` as a string (File path). Failures can raise `FileError` (The file could not be read). It returns `read_file` with `path`.
+
+<a id="symbol-LocalFiles.write"></a>
+### `LocalFiles.write` · [source](contracts.aug#L27)
+
+Write text. It takes `path` as a string (File path) and `content` as a string (Text). Failures can raise `FileError` (Writing failed). It calls `write_file` with `path` and `content`.
+
+<a id="symbol-Arguments"></a>
+## `Arguments` · capability interface · [source](contracts.aug#L31)
+
+Read command-line input through an explicit dependency.
+
+<a id="symbol-Arguments.read"></a>
+### `Arguments.read` · [source](contracts.aug#L32)
+
+It returns `List<string>`. It can call [`Arguments.read`](contracts.aug.md#symbol-Arguments.read).
+
+<a id="symbol-ProcessArguments"></a>
+## `ProcessArguments` · class · [source](contracts.aug#L35)
+
+Native command-line arguments. It implements [`Arguments`](contracts.aug.md#symbol-Arguments).
+
+<a id="symbol-ProcessArguments.read"></a>
+### `ProcessArguments.read` · [source](contracts.aug#L36)
+
+It returns `arguments`.
+
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/developer-workflow/.aug-spec/manifest.json

@@ -1,13 +1,13 @@
 {
   "format": 1,
   "files": [
-    ".aug-spec/august/0.19.0/io/contracts.aug",
-    ".aug-spec/august/0.19.0/io/contracts.aug.md",
+    ".aug-spec/august/0.21.0/io/contracts.aug",
+    ".aug-spec/august/0.21.0/io/contracts.aug.md",
     "calculator.aug.md",
     "logging/console.aug.md",
     "logging/export.aug.md",
     "logging/logger.aug.md",
     "main.aug.md"
   ],
-  "digest": "315eaa1aa7535c1e0d877120cc13528bdba05fb193bcba9e466597f98958b47b"
+  "digest": "44c597e8467c0fad529c3dba2db647157020dd0ec3ad4852e7c068b93934679c"
 }

package/examples/developer-workflow/calculator.aug

@@ -1,3 +1,4 @@
+// aug-spec: "calculator.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console and SystemConsole from august.io
 import Logger from logging
 /** Adds two integers. */
@@ -12,7 +13,7 @@ Calculator(resolve Logger logger to _logger) implements Arithmetic {
     * @param right Second integer.
     * @return Sum of the two integers.
     */
-    add(resolve Console console, int left, int right) returns int uses Console.write {
+    add(resolve Console console, int left, int right) {
         _logger.log(message="adding integers")
         return left + right
     }
@@ -22,7 +23,7 @@ Calculator(resolve Logger logger to _logger) implements Arithmetic {
 * @param fail Whether to simulate a failed load.
 * @throws FileError When fail is true.
 */
-load(bool fail) returns string unless FileError {
+load(bool fail) {
     if fail {
         throw FileError()
     }