@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/writing-docs.md

@@ -0,0 +1,49 @@
+# Writing the August documentation
+
+Write for a developer who wants to understand a program, complete a task, or check a rule. The wiki serves people trying August, engineers assessing it for a team, and developers working with coding agents. State what the current language does and show it in code. Design goals need explanation; claims of safety, speed, productivity, or production readiness need evidence and scope.
+
+The [editorial research](research/wiki-editorial-design.md) records the primary sources behind this approach. The Rust book informs the learning sequence; C's About page informs the compact introduction. Diátaxis informs the separate reading modes. Google's developer style guidance informs the prose. August's writing and examples are original.
+
+## Put a page in the right place
+
+| Reader's need | Place | What the page provides |
+| --- | --- | --- |
+| Learn a new concept | `docs/learn/` and `getting-started.md` | A runnable lesson with a goal, expected result, and next step. |
+| Complete a task | `docs/guides/` or an existing task guide | Direct actions, prerequisites, verification, and relevant limits. |
+| Look up exact behavior | Language, tooling, grammar, or generated API reference | Precise contracts and a consistent structure. |
+| Understand a design or assess the language | About, performance, readiness, compatibility, roadmap | Reasons, tradeoffs, and evidence. |
+| Maintain August | Contributor guides and research notes | Repository workflows and implementation details. |
+
+Keep existing URLs and anchors when a page still serves the same need. Add links to the lesson or task guide rather than turning the reference into a second book. Contributor processes belong under Contribute in navigation.
+
+## Explain it like a developer
+
+Open with the problem or operation the reader cares about. Introduce a program by saying what it does, then explain the important lines and their consequences. Use ordinary connected sentences and short paragraphs. Name actual declarations and commands. Explain unfamiliar terms when they first matter.
+
+Use lists for steps or parallel items and tables for comparisons. A prose explanation should not become a stack of bullets, headings, or signature dumps. Remove repeated summaries and promises that a topic will be explained later. Avoid promotional adjectives and claims that a procedure is easy. Precision matters more than brevity when a dependency, state change, failure, or limit could surprise the reader.
+
+For example, write: “The group constructs a new counter for each case. The second case still sees its initial value.” That explains the behavior a reader can observe. “Isolated test architecture enables scalable validation” does not.
+
+## Give examples a dependable path
+
+A lesson assumes the reader knows programming, not August. State where commands run, which files to save, and the output to expect. Introduce one new mechanism at a time where practical. Put detailed alternatives and edge cases in the reference and link them from the lesson.
+
+Install the published CLI once, then teach `aug init NAME` and `aug run`. Keep npx as an optional installation alternative. Continue lessons with short aug commands and offer complete example downloads. Reader instructions must not require cloning the language repository or running its internal CLI files. Source-workspace build and maintenance commands belong in contributor pages. Explain automatic dependency preparation and the system-tool prerequisites; distinguish creating files from preparing or executing a program.
+
+Complete runnable source uses `aug project=NAME file=PATH` fences and an entry in `docs/examples.json`. Fragments use `text` and explicitly say they are fragments. Before an intentional failure, say what change the reader is making and that checking or running it should fail; afterward explain the result and how to restore working code. Test important failing examples as well as successful ones when the lesson depends on that behavior.
+
+Handwritten lesson code is checked and run by `tests/documentation.test.mjs`, including nested Learn and Guides pages. `docs/lesson-failures.json` describes the book's tested mistake transformations and expected diagnostics. Generated gallery pages get their examples from `docs/example-projects.json` and `scripts/example-docs.mjs`. Edit those inputs, source, or Javadoc and regenerate; do not hand-edit generated Markdown.
+
+## Keep claims current
+
+Verify command names against CLI help and contracts against declarations, checker/runtime behavior, and regression tests. Do not infer semantics from a function's name. Keep release versions and installation availability in their canonical pages; link to them from introductions. A possible future command is not an installation instruction.
+
+Performance claims need a workload, compiler version, environment, methodology, and raw measurements. The homepage links to the benchmark page instead of duplicating numbers that can become stale. Do not treat microbenchmarks as evidence of agent productivity or general production readiness.
+
+An example involving security or deployment states its applicable limits nearby. Pending approval work and proposals remain labeled as such. Keep [readiness](production-readiness.md), the [roadmap](roadmap.md), and [library gaps](web-library-gaps.md) consistent with implemented behavior.
+
+## Review before publishing
+
+Follow [documentation maintenance](maintaining-docs.md) for generation and executable checks. Read the rendered page as a newcomer: can you find the first action, follow dependencies, understand the result, and locate the full contract? Check a narrow screen for long code and tables, and a wider screen for code/spec comparisons. Review copied source as well as visual wrapping.
+
+Research notes cite primary sources near the claims they support and distinguish findings from recommendations. Link research from contributor pages when it explains an editorial decision; users should not need to read the research to use August.

package/examples/{hello/.aug-spec/august/0.19.0 → approved-design/.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/approved-design/.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/approved-design/.aug-spec/manifest.json

@@ -1,8 +1,8 @@
 {
   "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",
     "counters.aug.md",
     "domain/app.aug.md",
     "domain/export.aug.md",
@@ -10,5 +10,5 @@
     "domain/numbers.aug.md",
     "main.aug.md"
   ],
-  "digest": "17b8a92022fe0e3becdd73b3eb31493a9cebe7ddeb63b1e76596c612ed728d88"
+  "digest": "a6219552bff760605d79d8e158b84db5cd48b192e0f7de2eef95a6e1c0089931"
 }

package/examples/approved-design/counters.aug

@@ -1,20 +1,21 @@
+// aug-spec: "counters.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Reading state has no mutation effect. */
 interface State:
 	read() returns int
 _Initial() implements State:
-	read() returns int:
+	read() :
 		return 0
 _Updated(int count) implements State:
-	read() returns int:
+	read() :
 		return count
 /** A mutable counter with an explicit transition contract. */
 interface Counter:
 	increment() changes self
 	value() returns int
 _Counter(resolve mutable State initial to _state) implements Counter:
-	increment() changes self:
+	increment() :
 		_state to _Updated(count=_state.read() + 1)
-	value() returns int:
+	value() :
 		return _state.read()
 /** The complete counter composition; its mutable state belongs to each scope. */
 composition Counters:

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

@@ -1,177 +1,70 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `counters.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`State`](counters.aug.md#symbol-State) is an interface.
-- [`_Initial`](counters.aug.md#symbol-_Initial) is a class implementing `State`.
-- [`_Updated`](counters.aug.md#symbol-_Updated) is a class implementing `State`.
-- [`Counter`](counters.aug.md#symbol-Counter) is an interface.
-- [`_Counter`](counters.aug.md#symbol-_Counter) is a class implementing `Counter`.
-- [`Counters`](counters.aug.md#symbol-Counters) declares 2 providers.
+# `counters.aug`
 
 <a id="symbol-State"></a>
-
-## `State`
-
-[source](counters.aug#L2)
-
-Interface.
-
-**Author documentation**
+## `State` · interface · [source](counters.aug#L3)
 
 Reading state has no mutation effect.
 
 <a id="symbol-State.read"></a>
+### `State.read` · [source](counters.aug#L4)
 
-### `State.read`
-
-[source](counters.aug#L3)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
+It returns `int`.
 
 <a id="symbol-Counter"></a>
-
-## `Counter`
-
-[source](counters.aug#L11)
-
-Interface.
-
-**Author documentation**
+## `Counter` · interface · [source](counters.aug#L12)
 
 A mutable counter with an explicit transition contract.
 
 <a id="symbol-Counter.increment"></a>
+### `Counter.increment` · [source](counters.aug#L13)
 
-### `Counter.increment`
-
-[source](counters.aug#L12)
-
-Returns: no value.
-
-May change: `self`.
-
-Interface contract. A selected implementation supplies the behavior.
+It may change `self`.
 
 <a id="symbol-Counter.value"></a>
+### `Counter.value` · [source](counters.aug#L14)
 
-### `Counter.value`
-
-[source](counters.aug#L13)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
+It returns `int`.
 
 <a id="symbol-Counters"></a>
-
-## `Counters`
-
-[source](counters.aug#L20)
-
-**Author documentation**
+## `Counters` · [source](counters.aug#L21)
 
 The complete counter composition; its mutable state belongs to each scope.
 
-This composition declares these providers before startup:
-
-- Provide [`_Initial`](counters.aug.md#symbol-_Initial) when `State` is requested. Reuse one instance.
-- Provide [`_Counter`](counters.aug.md#symbol-_Counter) when `Counter` is requested. Reuse one instance per explicit scope. Permit explicit shared mutation. Required dependencies: `State`.
+These providers are registered before startup. `State` is provided by [`_Initial`](counters.aug.md#symbol-_Initial). The same instance is shared. `Counter` is provided by [`_Counter`](counters.aug.md#symbol-_Counter). Each scope shares one instance. Shared mutation is allowed. It requires bindings for `State`.
 
 <a id="symbol-_Initial"></a>
+## `_Initial` · class · [source](counters.aug#L5)
 
-## `_Initial`
-
-[source](counters.aug#L4)
-
-Behavioral class, private to this file.
-
-Satisfies [`State`](counters.aug.md#symbol-State).
+It implements [`State`](counters.aug.md#symbol-State). It is private to this file.
 
 <a id="symbol-_Initial.read"></a>
+### `_Initial.read` · [source](counters.aug#L6)
 
-### `_Initial.read`
-
-[source](counters.aug#L5)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `0`.
+It returns `0`.
 
 <a id="symbol-_Updated"></a>
+## `_Updated` · class · [source](counters.aug#L8)
 
-## `_Updated`
-
-[source](counters.aug#L7)
-
-Behavioral class, private to this file.
-
-Satisfies [`State`](counters.aug.md#symbol-State).
-
-**Inputs**
-
-- `count` (`int`) — required labeled input — stored as `count` and read-only after initialization.
+It implements [`State`](counters.aug.md#symbol-State). It is private to this file. It takes `count` as an integer, kept read-only.
 
 <a id="symbol-_Updated.read"></a>
+### `_Updated.read` · [source](counters.aug#L9)
 
-### `_Updated.read`
-
-[source](counters.aug#L8)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `count`.
+It returns `count`.
 
 <a id="symbol-_Counter"></a>
+## `_Counter` · class · [source](counters.aug#L15)
 
-## `_Counter`
-
-[source](counters.aug#L14)
-
-Behavioral class, private to this file.
-
-Satisfies [`Counter`](counters.aug.md#symbol-Counter).
-
-**Inputs**
-
-- `initial` ([`State`](counters.aug.md#symbol-State)) — injected; callers omit it — stored as `_state` (private) and mutable.
+It implements [`Counter`](counters.aug.md#symbol-Counter). It is private to this file. The `_state` dependency is injected as [`State`](counters.aug.md#symbol-State) and stored mutably and privately.
 
 <a id="symbol-_Counter.increment"></a>
+### `_Counter.increment` · [source](counters.aug#L16)
 
-### `_Counter.increment`
-
-[source](counters.aug#L15)
-
-Returns: no value.
-
-May change: `self`.
-
-**What it does**
-
-- Set `_state` to call [`_Updated`](counters.aug.md#symbol-_Updated) with `count` = (call [`State.read`](counters.aug.md#symbol-State.read) on `_state` plus `1`).
+It may change `self`. It sets `_state` to a [`_Updated`](counters.aug.md#symbol-_Updated) with `count` from [`_state.read`](counters.aug.md#symbol-State.read) plus `1`.
 
 <a id="symbol-_Counter.value"></a>
+### `_Counter.value` · [source](counters.aug#L18)
 
-### `_Counter.value`
-
-[source](counters.aug#L17)
-
-Returns: `int`.
-
-**What it does**
-
-- Return call [`State.read`](counters.aug.md#symbol-State.read) on `_state`.
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It returns [`_state.read`](counters.aug.md#symbol-State.read).

package/examples/approved-design/domain/app.aug

@@ -1,3 +1,4 @@
+// aug-spec: "app.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Console from august.io
 import Fruit from models
 /** The application's explicit startup operation. */
@@ -6,7 +7,7 @@ interface Application:
 	start() uses Console.write
 /** Construction stores dependencies; start performs the visible external work. */
 ApplicationImpl(resolve Console console) implements Application:
-	start() uses console.write:
+	start() :
 		fruit to [Fruit(code=1, name="apple"), Fruit(name="pear", code=2)]
 		for item in fruit:
 			console.write(value=item.name)

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

@@ -1,97 +1,27 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `app.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`Application`](app.aug.md#symbol-Application) is an interface.
-- [`ApplicationImpl`](app.aug.md#symbol-ApplicationImpl) is a class implementing `Application`.
+# `app.aug`
 
 <a id="symbol-Application"></a>
-
-## `Application`
-
-[source](app.aug#L4)
-
-Interface.
-
-**Author documentation**
+## `Application` · interface · [source](app.aug#L5)
 
 The application's explicit startup operation.
 
 <a id="symbol-Application.start"></a>
+### `Application.start` · [source](app.aug#L7)
 
-### `Application.start`
-
-[source](app.aug#L6)
-
-Returns: no value.
-
-Capabilities: [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-Interface contract. A selected implementation supplies the behavior.
-
-**Author documentation**
-
-Writes the fruit names through the selected console.
+Writes the fruit names through the selected console. It can call [`Console.write`](../.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-Console.write).
 
 <a id="symbol-ApplicationImpl"></a>
+## `ApplicationImpl` · class · [source](app.aug#L9)
 
-## `ApplicationImpl`
-
-[source](app.aug#L8)
-
-Behavioral class.
-
-Satisfies [`Application`](app.aug.md#symbol-Application).
-
-**Author documentation**
-
-Construction stores dependencies; start performs the visible external work.
-
-**Inputs**
-
-- `console` ([`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)) — injected; callers omit it — stored as `console` and read-only after initialization.
+Construction stores dependencies; start performs the visible external work. It implements [`Application`](app.aug.md#symbol-Application). The `console` dependency is injected as [`Console`](../.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-Console) and stored read-only.
 
 <a id="symbol-ApplicationImpl.start"></a>
+### `ApplicationImpl.start` · [source](app.aug#L10)
 
-### `ApplicationImpl.start`
-
-[source](app.aug#L9)
-
-Returns: no value.
-
-Capabilities: [`console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write).
-
-**What it does**
-
-- Set `fruit` to a list containing call [`Fruit`](models.aug.md#symbol-Fruit) with `code` = `1`; `name` = `"apple"`, call [`Fruit`](models.aug.md#symbol-Fruit) with `name` = `"pear"`; `code` = `2`.
-- For each `item` in a snapshot of `fruit`, in iteration order:
-  - Call [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write) on `console` with `value` = `name` of `item`.
-
-**Author documentation**
-
-Writes the fruit names through the selected console.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Console`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console)
-
-Capability interface from `august.io`.
-
-- [`Console.write`](../.aug-spec/august/0.19.0/io/contracts.aug.md#symbol-Console.write)<`T`> (`value`: `T`) → `void`.
-
-### [`Fruit`](models.aug.md#symbol-Fruit)
-
-Record from `models`.
-
-- Construct with `code`: `int`, `name`: `string` → [`Fruit`](models.aug.md#symbol-Fruit).
-- Read `name` (`string`).
+Writes the fruit names through the selected console. It sets `fruit` to a list containing a [`Fruit`](models.aug.md#symbol-Fruit) with `code` `1` and `name` `"apple"`, a [`Fruit`](models.aug.md#symbol-Fruit) with `name` `"pear"` and `code` `2`. For each `item` in a snapshot of `fruit`, it passes `item.name` to [`console.write`](../.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-Console.write).
 
-## Shared language rules
+## Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Console`](../.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-Console) ([`write`](../.aug-spec/august/0.21.0/io/contracts.aug.md#symbol-Console.write)) from `august.io`. It uses [`Fruit`](models.aug.md#symbol-Fruit) (`name`) from `models`.

package/examples/approved-design/domain/export.aug

@@ -1,3 +1,4 @@
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export Application from app
 export ApplicationImpl from app
 export Fruit from models

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

@@ -1,25 +1,9 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `export.aug` specification
+# `export.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Exports
 
-## In this file
+Export the declaration `Application` from [`app.aug`](app.aug.md#symbol-Application). Export the declaration `ApplicationImpl` from [`app.aug`](app.aug.md#symbol-ApplicationImpl). Export the declaration `Fruit` from [`models.aug`](models.aug.md#symbol-Fruit). Export the declaration `double` from [`numbers.aug`](numbers.aug.md#symbol-double).
 
-- Export `Application` from this folder.
-- Export `ApplicationImpl` from this folder.
-- Export `Fruit` from this folder.
-- Export `double` from this folder.
-- Export `RangeError` from this folder.
-
-## Folder exports
-
-- Export the declaration `Application` from [`app.aug`](app.aug.md#symbol-Application).
-- Export the declaration `ApplicationImpl` from [`app.aug`](app.aug.md#symbol-ApplicationImpl).
-- Export the declaration `Fruit` from [`models.aug`](models.aug.md#symbol-Fruit).
-- Export the declaration `double` from [`numbers.aug`](numbers.aug.md#symbol-double).
-- Export the declaration `RangeError` from [`numbers.aug`](numbers.aug.md#symbol-RangeError).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `RangeError` from [`numbers.aug`](numbers.aug.md#symbol-RangeError).

package/examples/approved-design/domain/models.aug

@@ -1,2 +1,3 @@
+// aug-spec: "models.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Immutable fruit data, with public construction labels and structural equality. */
 record Fruit(int code, string name)

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

@@ -1,30 +1,8 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `models.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`Fruit`](models.aug.md#symbol-Fruit) is an immutable record.
+# `models.aug`
 
 <a id="symbol-Fruit"></a>
+## `Fruit` · immutable record · [source](models.aug#L3)
 
-## `Fruit`
-
-[source](models.aug#L2)
-
-Immutable record.
-
-**Author documentation**
-
-Immutable fruit data, with public construction labels and structural equality.
-
-**Inputs**
-
-- `code` (`int`) — required labeled input — stored as `code` and read-only after initialization.
-- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Immutable fruit data, with public construction labels and structural equality. It takes `code` as an integer, kept read-only and `name` as a string, kept read-only.

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

@@ -1,9 +1,10 @@
+// aug-spec: "numbers.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Raised when an input is outside the operation's domain. */
 RangeError(int value) implements Error:
 	pass
 /** A pure validation layer, shared by any compatible callable. */
 interceptor Positive<T>():
-	around(int amount) returns T unless RangeError:
+	around(int amount) returns T :
 		if amount < 0:
 			throw RangeError(value=amount)
 		return next()
@@ -14,7 +15,7 @@ interceptor Positive<T>():
 * @throws RangeError A validation layer rejected a negative input.
 */
 [Positive]
-double(int amount) returns int:
+double(int amount) :
 	return amount * 2
 test double:
 	when "positive":