@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/oidc-login/provider/userinfo.md

@@ -49,12 +49,13 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "userinfo.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import UserInfo and AccessGrant from contracts
 import securityHeaders from common
-import Clock from august.time
-import ExpiringStore from august.memory
+import Clock from time
+import ExpiringStore from memory
 /** The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response. */
-endpoint GET "/provider/userinfo" as userinfo(optional string authorization from header, resolve Clock clock, resolve ExpiringStore<AccessGrant> access) returns HttpResponse<Json> uses clock.now and access.get unless TimeError and HttpError:
+endpoint GET "/provider/userinfo" as userinfo(optional string authorization from header, resolve Clock clock, resolve ExpiringStore<AccessGrant> access):
     match authorization:
         when null:
             pass
@@ -69,20 +70,33 @@ endpoint GET "/provider/userinfo" as userinfo(optional string authorization from
                                 when null:
                                     pass
                                 when some grant:
-                                    return HttpResponse(body=Json(value=UserInfo(sub=grant.subject, name=grant.name)), headers=securityHeaders())
+                                    return HttpResponse(
+                                        body=Json(
+                                            value=UserInfo(sub=grant.subject, name=grant.name)
+                                        ),
+                                        headers=securityHeaders()
+                                    )
                 catch IndexError error:
                     pass
-    headers = securityHeaders().with(name="www-authenticate", value="Bearer error=\"invalid_token\"")
-    return HttpResponse(body=Json(value={"error": "invalid_token"}), status=401, headers=headers)
+    headers = securityHeaders().with(
+        name="www-authenticate",
+        value="Bearer error=\"invalid_token\""
+    )
+    return HttpResponse(
+        body=Json(value={"error": "invalid_token"}),
+        status=401,
+        headers=headers
+    )
 ```
 
 ```aug [Braces]
+// aug-spec: "userinfo.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import UserInfo and AccessGrant from contracts
 import securityHeaders from common
-import Clock from august.time
-import ExpiringStore from august.memory
+import Clock from time
+import ExpiringStore from memory
 /** The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response. */
-endpoint GET "/provider/userinfo" as userinfo(optional string authorization from header, resolve Clock clock, resolve ExpiringStore<AccessGrant> access) returns HttpResponse<Json> uses clock.now and access.get unless TimeError and HttpError {
+endpoint GET "/provider/userinfo" as userinfo(optional string authorization from header, resolve Clock clock, resolve ExpiringStore<AccessGrant> access) {
     match authorization {
         when null {
             pass
@@ -99,7 +113,12 @@ endpoint GET "/provider/userinfo" as userinfo(optional string authorization from
                                     pass
                                 }
                                 when some grant {
-                                    return HttpResponse(body=Json(value=UserInfo(sub=grant.subject, name=grant.name)), headers=securityHeaders())
+                                    return HttpResponse(
+                                        body=Json(
+                                            value=UserInfo(sub=grant.subject, name=grant.name)
+                                        ),
+                                        headers=securityHeaders()
+                                    )
                                 }
                             }
                         }
@@ -111,8 +130,15 @@ endpoint GET "/provider/userinfo" as userinfo(optional string authorization from
             }
         }
     }
-    headers = securityHeaders().with(name="www-authenticate", value="Bearer error=\"invalid_token\"")
-    return HttpResponse(body=Json(value={"error": "invalid_token"}), status=401, headers=headers)
+    headers = securityHeaders().with(
+        name="www-authenticate",
+        value="Bearer error=\"invalid_token\""
+    )
+    return HttpResponse(
+        body=Json(value={"error": "invalid_token"}),
+        status=401,
+        headers=headers
+    )
 }
 ```
 
@@ -124,104 +150,23 @@ endpoint GET "/provider/userinfo" as userinfo(optional string authorization from
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
 
-### In this file
+### `userinfo` · [source](userinfo.md#code) {#symbol-userinfo}
 
-- [`userinfo`](userinfo.md#symbol-userinfo) handles `GET` `/provider/userinfo` returning `HttpResponse<Json>`.
+`userinfo` handles `GET /provider/userinfo`. The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response.
 
-### `userinfo` {#symbol-userinfo}
+It takes `authorization` as `optional string` from the HTTP header. It gets `clock` ([`Clock`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock)) and `access` ([`ExpiringStore<AccessGrant>`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore)) from dependency injection. Omitted optional inputs are null. It can also raise `HttpError` and `TimeError`.
 
-[source](userinfo.md#code)
+If `authorization` is null, it continues without an operation. If `authorization` is not null, using `header` for it sets `parts` to `header.split` with `separator` `" "`. If the number of elements in `parts` equals `2`, if the item at index `0` in `parts` equals `"Bearer"`, it sets `token` to the item at index `1` in `parts`. If `token` is a URL-safe ASCII token with `43` to `43` characters, if [`access.get`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.get) with `key` from `token` and `now` from [`clock.now`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock.now) is null, it continues without an operation.
 
-**Inputs**
+If [`access.get`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.get) with `key` from `token` and `now` from [`clock.now`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock.now) is not null, using `grant` for it returns HTTP 200 with a `Json` with `value` from an [`UserInfo`](contracts.md#symbol-UserInfo) with `sub` from `grant.subject` and `grant.name` and [`securityHeaders`](../common/headers.md#symbol-securityHeaders) headers. If this work raises `IndexError`, it continues without an operation. It sets `headers` to [`securityHeaders`](../common/headers.md#symbol-securityHeaders) with the header `"www-authenticate"` set to `"Bearer error=\"invalid_token\""`. It returns HTTP 401 with a `Json` with `value` from a map with `"error"` mapped to `"invalid_token"` and `headers` headers.
 
-- `authorization` (`optional string`) — read from the HTTP header; absent value becomes null.
-- `clock` ([`Clock`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock)) — injected; callers omit it.
-- `access` ([`ExpiringStore<AccessGrant>`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)) — injected; callers omit it.
+### Dependencies
 
-Returns: `HttpResponse<Json>`.
+It uses [`ExpiringStore`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore) ([`get`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.get)) from `memory`. It uses [`Clock`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock) ([`now`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock.now)) from `time`. It uses [`securityHeaders`](../common/headers.md#symbol-securityHeaders) from `common`. It uses [`AccessGrant`](contracts.md#symbol-AccessGrant) (`name` and `subject`) and [`UserInfo`](contracts.md#symbol-UserInfo) from `contracts`.
 
-Capabilities: [`clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now), [`access.get`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.get).
-
-Can fail with `TimeError`, `HttpError`. Callers must catch or propagate these errors.
-
-HTTP route: `GET` `/provider/userinfo`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
-
-**What it does**
-
-- Select the matching case for `authorization`:
-  - A null value, including omitted optional input:
-    - Continue without another operation.
-  - A present, non-null value, named `header`:
-    - Set `parts` to call `split` on `header` with `separator` = `" "`.
-    - If call `length` on `parts` equals `2`:
-      - Try these operations:
-        - If call `get` on `parts` with `index` = `0` equals `"Bearer"`:
-          - Set `token` to call `get` on `parts` with `index` = `1`.
-          - If call `isToken` on `token` with `min` = `43`; `max` = `43` is true:
-            - Select the matching case for call [`ExpiringStore.get`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.get) on `access` with `key` = `token`; `now` = call [`Clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now) on `clock`:
-              - A null value, including omitted optional input:
-                - Continue without another operation.
-              - A present, non-null value, named `grant`:
-                - Return call `HttpResponse` with `body` = call `Json` with `value` = call [`UserInfo`](contracts.md#symbol-UserInfo) with `sub` = `subject` of `grant`; `name` = `name` of `grant`; `headers` = call [`securityHeaders`](../common/headers.md#symbol-securityHeaders).
-      - If they fail with `IndexError`, name the failure `error` and recover:
-        - Continue without another operation.
-- Set `headers` to call `with` on call [`securityHeaders`](../common/headers.md#symbol-securityHeaders) with `name` = `"www-authenticate"`; `value` = `"Bearer error=\"invalid_token\""`.
-- Return call `HttpResponse` with `body` = call `Json` with `value` = a map with `"error"` mapped to `"invalid_token"`; `status` = `401`; `headers` = `headers`.
-
-**Author documentation**
-
-The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`ExpiringStore`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)
-
-Capability interface from `august.memory`.
-
-- [`ExpiringStore.get`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.get) (`key`: `string`, `now`: `int`) → `optional T`.
-
-#### [`Clock`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock)
-
-Capability interface from `august.time`.
-
-- [`Clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now) (no caller inputs) → `int`; can fail with `TimeError`.
-
-#### [`securityHeaders`](../common/headers.md#symbol-securityHeaders)
-
-Function from `common`.
-
-- [`securityHeaders`](../common/headers.md#symbol-securityHeaders) (no caller inputs) → `Headers`; can fail with `HttpError`.
-
-#### [`AccessGrant`](contracts.md#symbol-AccessGrant)
-
-Record from `contracts`.
-
-- Read `name` (`string`).
-- Read `subject` (`string`).
-
-#### [`UserInfo`](contracts.md#symbol-UserInfo)
-
-Record from `contracts`.
-
-- Construct with `sub`: `string`, `name`: `string` → [`UserInfo`](contracts.md#symbol-UserInfo).
-
-### Built-in operations used by this file
-
-- `Headers.with` (`name`: `string`, `value`: `string`) → `Headers`: Return new headers with one additional validated field. Header names ignore case; duplicate values remain separate. Can fail with `HttpError`.
-- `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.
-- `string.isToken` (`min`: `int`, `max`: `int`) → `bool`: Require an ASCII RFC 3986 unreserved token with a bounded length.
-- `string.split` (`separator`: `string`) → `List<string>`: Split at an exact separator, preserving empty parts.
-
-[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/docs/examples/oidc-login/provider/views.md

@@ -49,21 +49,23 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "views.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Page from common
 /** A server form with a checked HTTP action. The browser submits to the provider endpoint. */
-ProviderLogin(string requestId, string csrf, string message, HttpAction submit) returns Html:
+ProviderLogin(string requestId, string csrf, string message, HttpAction submit):
     return <Page title={"Sign in with the August provider"}><p>{message}</p><p style={"background:#f3f5f9;padding:12px;border-radius:8px"}>Demo account: <strong>ada</strong> · password <strong>august-demo</strong></p><form method={"post"} action={"/provider/login"} onSubmit={submit}><input type={"hidden"} name={"request_id"} value={requestId} /><input type={"hidden"} name={"csrf"} value={csrf} /><p><label for={"username"}>Username</label><br /><input id={"username"} name={"username"} autocomplete={"username"} value={"ada"} maxlength={"64"} required={true} style={"padding:10px;width:90%"} /></p><p><label for={"password"}>Password</label><br /><input id={"password"} type={"password"} name={"password"} autocomplete={"current-password"} maxlength={"256"} required={true} style={"padding:10px;width:90%"} /></p><button type={"submit"} style={"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"}>Sign in and return to the app</button></form><p style={"font-size:14px;color:#677189"}>The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.</p></Page>
-ProviderFailure(string message) returns Html:
+ProviderFailure(string message):
     return <Page title={"Sign-in could not continue"}><p>{message}</p><a href={"/login/start"}>Start a new sign-in</a></Page>
 ```
 
 ```aug [Braces]
+// aug-spec: "views.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Page from common
 /** A server form with a checked HTTP action. The browser submits to the provider endpoint. */
-ProviderLogin(string requestId, string csrf, string message, HttpAction submit) returns Html {
+ProviderLogin(string requestId, string csrf, string message, HttpAction submit) {
     return <Page title={"Sign in with the August provider"}><p>{message}</p><p style={"background:#f3f5f9;padding:12px;border-radius:8px"}>Demo account: <strong>ada</strong> · password <strong>august-demo</strong></p><form method={"post"} action={"/provider/login"} onSubmit={submit}><input type={"hidden"} name={"request_id"} value={requestId} /><input type={"hidden"} name={"csrf"} value={csrf} /><p><label for={"username"}>Username</label><br /><input id={"username"} name={"username"} autocomplete={"username"} value={"ada"} maxlength={"64"} required={true} style={"padding:10px;width:90%"} /></p><p><label for={"password"}>Password</label><br /><input id={"password"} type={"password"} name={"password"} autocomplete={"current-password"} maxlength={"256"} required={true} style={"padding:10px;width:90%"} /></p><button type={"submit"} style={"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"}>Sign in and return to the app</button></form><p style={"font-size:14px;color:#677189"}>The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.</p></Page>
 }
-ProviderFailure(string message) returns Html {
+ProviderFailure(string message) {
     return <Page title={"Sign-in could not continue"}><p>{message}</p><a href={"/login/start"}>Start a new sign-in</a></Page>
 }
 ```
@@ -76,61 +78,19 @@ ProviderFailure(string message) returns Html {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `ProviderLogin` · [source](views.md#code) {#symbol-ProviderLogin}
 
-### In this file
+A server form with a checked HTTP action. The browser submits to the provider endpoint. It takes `requestId`, `csrf`, and `message` as strings and `submit` as `HttpAction`.
 
-- [`ProviderLogin`](views.md#symbol-ProviderLogin) is a function returning `Html`.
-- [`ProviderFailure`](views.md#symbol-ProviderFailure) is a function returning `Html`.
+It returns the server component [`Page`](../common/views.md#symbol-Page) with `title` = `"Sign in with the August provider"` containing a paragraph containing `message` with escaped text, a paragraph with `style` = `"background:#f3f5f9;padding:12px;border-radius:8px"` containing `Demo account: `, the HTML element `strong` containing `ada` with escaped text, ` · password `, the HTML element `strong` containing `august-demo` with escaped text with escaped text, the HTML element `form` with `method` = `"post"`, `action` = `"/provider/login"`, `onSubmit` = `submit` containing the HTML element `input` with `type` = `"hidden"`, `name` = `"request_id"`, `value` = `requestId` with escaped text, the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `csrf` with escaped text, a paragraph containing the HTML element `label` with `for` = `"username"` containing `Username` with escaped text, the HTML element `br` with escaped text, the HTML element `input` with `id` = `"username"`, `name` = `"username"`, `autocomplete` = `"username"`, `value` = `"ada"`, `maxlength` = `"64"`, `required` = `true`, `style` = `"padding:10px;width:90%"` with escaped text with escaped text, a paragraph containing the HTML element `label` with `for` = `"password"` containing `Password` with escaped text, the HTML element `br` with escaped text, the HTML element `input` with `id` = `"password"`, `type` = `"password"`, `name` = `"password"`, `autocomplete` = `"current-password"`, `maxlength` = `"256"`, `required` = `true`, `style` = `"padding:10px;width:90%"` with escaped text with escaped text, a button with `type` = `"submit"`, `style` = `"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"` containing `Sign in and return to the app` with escaped text with escaped text, a paragraph with `style` = `"font-size:14px;color:#677189"` containing `The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.` with escaped text with escaped text.
 
-### `ProviderLogin` {#symbol-ProviderLogin}
+### `ProviderFailure` · [source](views.md#code) {#symbol-ProviderFailure}
 
-[source](views.md#code)
+It takes `message` as a string. It returns the server component [`Page`](../common/views.md#symbol-Page) with `title` = `"Sign-in could not continue"` containing a paragraph containing `message` with escaped text, a link with `href` = `"/login/start"` containing `Start a new sign-in` with escaped text with escaped text.
 
-**Inputs**
+### Dependencies
 
-- `requestId` (`string`) — required labeled input.
-- `csrf` (`string`) — required labeled input.
-- `message` (`string`) — required labeled input.
-- `submit` (`HttpAction`) — required labeled input.
-
-Returns: `Html`.
-
-**What it does**
-
-- Return the server component [`Page`](../common/views.md#symbol-Page) with `title` = `"Sign in with the August provider"` containing the HTML element `p` containing `message` (rendered on the server with embedded text escaped), the HTML element `p` with `style` = `"background:#f3f5f9;padding:12px;border-radius:8px"` containing `Demo account: `, the HTML element `strong` containing `ada` (rendered on the server with embedded text escaped), ` · password `, the HTML element `strong` containing `august-demo` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `form` with `method` = `"post"`, `action` = `"/provider/login"`, `onSubmit` = `submit` containing the HTML element `input` with `type` = `"hidden"`, `name` = `"request_id"`, `value` = `requestId` (rendered on the server with embedded text escaped), the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `csrf` (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `label` with `for` = `"username"` containing `Username` (rendered on the server with embedded text escaped), the HTML element `br` (rendered on the server with embedded text escaped), the HTML element `input` with `id` = `"username"`, `name` = `"username"`, `autocomplete` = `"username"`, `value` = `"ada"`, `maxlength` = `"64"`, `required` = `true`, `style` = `"padding:10px;width:90%"` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `label` with `for` = `"password"` containing `Password` (rendered on the server with embedded text escaped), the HTML element `br` (rendered on the server with embedded text escaped), the HTML element `input` with `id` = `"password"`, `type` = `"password"`, `name` = `"password"`, `autocomplete` = `"current-password"`, `maxlength` = `"256"`, `required` = `true`, `style` = `"padding:10px;width:90%"` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `button` with `type` = `"submit"`, `style` = `"padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit"` containing `Sign in and return to the app` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` with `style` = `"font-size:14px;color:#677189"` containing `The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
-
-**Author documentation**
-
-A server form with a checked HTTP action. The browser submits to the provider endpoint.
-
-### `ProviderFailure` {#symbol-ProviderFailure}
-
-[source](views.md#code)
-
-**Inputs**
-
-- `message` (`string`) — required labeled input.
-
-Returns: `Html`.
-
-**What it does**
-
-- Return the server component [`Page`](../common/views.md#symbol-Page) with `title` = `"Sign-in could not continue"` containing the HTML element `p` containing `message` (rendered on the server with embedded text escaped), the HTML element `a` with `href` = `"/login/start"` containing `Start a new sign-in` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Page`](../common/views.md#symbol-Page)
-
-Function from `common`.
-
-- [`Page`](../common/views.md#symbol-Page) (`title`: `string`, `children`: `List<Html>`) → `Html`.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`Page`](../common/views.md#symbol-Page) from `common`.
 
 ::::
 

package/docs/examples/ownership/counter.md

@@ -29,11 +29,12 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 Counter(mutable int value) implements ICounter:
-    increment() changes self:
+    increment():
         borrow self:
             value = value + 1
-    read() returns int:
+    read():
         return value
 interface ICounter:
     increment() changes self
@@ -41,13 +42,14 @@ interface ICounter:
 ```
 
 ```aug [Braces]
+// aug-spec: "counter.aug.md" explains this file. Read it before changes; refresh with aug spec.
 Counter(mutable int value) implements ICounter {
-    increment() changes self {
+    increment() {
         borrow self {
             value = value + 1
         }
     }
-    read() returns int {
+    read() {
         return value
     }
 }
@@ -65,75 +67,27 @@ interface ICounter {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `Counter` · class · [source](counter.md#code) {#symbol-Counter}
 
-### In this file
+It implements [`ICounter`](counter.md#symbol-ICounter). It takes `value` as an integer, kept mutable.
 
-- [`Counter`](counter.md#symbol-Counter) is a class implementing `ICounter`.
-- [`ICounter`](counter.md#symbol-ICounter) is an interface.
+#### `Counter.increment` · [source](counter.md#code) {#symbol-Counter.increment}
 
-### `Counter` {#symbol-Counter}
+It may change `self`. With temporary permission to change `self`, it increases `value` by `1`.
 
-[source](counter.md#code)
+#### `Counter.read` · [source](counter.md#code) {#symbol-Counter.read}
 
-Behavioral class.
+It returns `value`.
 
-Satisfies [`ICounter`](counter.md#symbol-ICounter).
+### `ICounter` · interface · [source](counter.md#code) {#symbol-ICounter}
 
-**Inputs**
+#### `ICounter.increment` · [source](counter.md#code) {#symbol-ICounter.increment}
 
-- `value` (`int`) — required labeled input — stored as `value` and mutable.
+It may change `self`.
 
-#### `Counter.increment` {#symbol-Counter.increment}
+#### `ICounter.read` · [source](counter.md#code) {#symbol-ICounter.read}
 
-[source](counter.md#code)
-
-Returns: no value.
-
-May change: `self`.
-
-**What it does**
-
-- Grant exclusive mutable access to `self` for this block, then end the borrow:
-  - Set `value` to `value` plus `1`.
-
-#### `Counter.read` {#symbol-Counter.read}
-
-[source](counter.md#code)
-
-Returns: `int`.
-
-**What it does**
-
-- Return `value`.
-
-### `ICounter` {#symbol-ICounter}
-
-[source](counter.md#code)
-
-Interface.
-
-#### `ICounter.increment` {#symbol-ICounter.increment}
-
-[source](counter.md#code)
-
-Returns: no value.
-
-May change: `self`.
-
-Interface contract. A selected implementation supplies the behavior.
-
-#### `ICounter.read` {#symbol-ICounter.read}
-
-[source](counter.md#code)
-
-Returns: `int`.
-
-Interface contract. A selected implementation supplies the behavior.
-
-### Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It returns `int`.
 
 ::::
 

package/docs/examples/ownership/index.md

@@ -12,7 +12,7 @@ outline: [2, 3]
 
 Share a reference for reading and grant explicit access for mutation.
 
-Read a file below to see its highlighted source and the Markdown produced by `aug spec`. Choose **Indentation** or **Braces** above the code. Both views describe the same checked program; your choice is kept when you open another file.
+Open a file to read its source beside the explanation produced by `aug spec`. **Indentation** and **Braces** display the same checked program; your choice carries across file pages.
 
 ## Project files
 
@@ -22,12 +22,13 @@ Read a file below to see its highlighted source and the Markdown produced by `au
 
 ## Try this project
 
-From a repository checkout with August installed:
+[Download this project](/downloads/ownership.zip), then extract the archive in an empty working folder. It contains the checked source, configuration, and generated specs. [Install August](../../getting-started.md) once, then run these commands. Native libraries are prepared automatically when needed:
 
 ```sh
-aug check examples/ownership
-aug spec examples/ownership
-aug run examples/ownership
+cd ownership
+aug check .
+aug spec .
+aug run .
 ```
 
 [Browse all examples](../index.md)

package/docs/examples/ownership/main.md

@@ -29,6 +29,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 own Counter counter = Counter(value=1)
 counter.increment()
@@ -36,6 +37,7 @@ print(value=counter.read())
 ```
 
 ```aug [Braces]
+// aug-spec: "main.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import Counter from counter
 own Counter counter = Counter(value=1)
 counter.increment()
@@ -50,40 +52,15 @@ print(value=counter.read())
 
 ## Compiled specification {#specification}
 
-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 `counter` of type [`Counter`](counter.md#symbol-Counter) to a [`Counter`](counter.md#symbol-Counter) with `value` `1`. `counter` of type [`Counter`](counter.md#symbol-Counter) owns this value. It calls [`counter.increment`](counter.md#symbol-Counter.increment). It prints [`counter.read`](counter.md#symbol-Counter.read).
 
-- Run 3 other startup steps in source order.
+### Dependencies
 
-### Startup, in source order
+It uses [`Counter`](counter.md#symbol-Counter) ([`increment`](counter.md#symbol-Counter.increment) and [`read`](counter.md#symbol-Counter.read)) from `counter`.
 
-- Set `counter` of type [`Counter`](counter.md#symbol-Counter) to call [`Counter`](counter.md#symbol-Counter) with `value` = `1`.
-- This variable owns the value.
-- Call [`Counter.increment`](counter.md#symbol-Counter.increment) on `counter`.
-- Call `print` with `value` = call [`Counter.read`](counter.md#symbol-Counter.read) on `counter`.
-
-### Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-#### [`Counter`](counter.md#symbol-Counter)
-
-Class from `counter`.
-
-- Construct with `value`: `int` → [`Counter`](counter.md#symbol-Counter).
-- [`Counter.increment`](counter.md#symbol-Counter.increment) (no caller inputs) → `void`; changes `self`.
-- [`Counter.read`](counter.md#symbol-Counter.read) (no caller inputs) → `int`.
-
-### Built-in operations used by this file
-
-- `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).
 
 ::::