@greenpandastudios/aug-cli 0.19.0

package/docs/examples/visibility/counter.md

@@ -0,0 +1,142 @@
+---
+title: "counter.aug · Private state and helpers"
+generated: true
+source: "examples/visibility/counter.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `counter.aug`
+
+[Private state and helpers](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`counter.aug`](counter.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+interface ICounter:
+    label() returns string
+Counter(mutable int value) implements ICounter:
+    _label() returns string:
+        return _prefix()
+    label() returns string:
+        return self._label()
+_prefix() returns string:
+    return "count"
+```
+
+```aug [Braces]
+interface ICounter {
+    label() returns string
+}
+Counter(mutable int value) implements ICounter {
+    _label() returns string {
+        return _prefix()
+    }
+    label() returns string {
+        return self._label()
+    }
+}
+_prefix() returns string {
+    return "count"
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- [`ICounter`](counter.md#symbol-ICounter) is an interface.
+- [`Counter`](counter.md#symbol-Counter) is a class implementing `ICounter`.
+- [`_prefix`](counter.md#symbol-_prefix) is a function returning `string`.
+
+### `ICounter` {#symbol-ICounter}
+
+[source](counter.md#code)
+
+Interface.
+
+#### `ICounter.label` {#symbol-ICounter.label}
+
+[source](counter.md#code)
+
+Returns: `string`.
+
+Interface contract. A selected implementation supplies the behavior.
+
+### `Counter` {#symbol-Counter}
+
+[source](counter.md#code)
+
+Behavioral class.
+
+Satisfies [`ICounter`](counter.md#symbol-ICounter).
+
+**Inputs**
+
+- `value` (`int`) — required labeled input — stored as `value` and mutable.
+
+#### `Counter._label` {#symbol-Counter._label}
+
+[source](counter.md#code)
+
+Private to its defining scope.
+
+Returns: `string`.
+
+**What it does**
+
+- Return call [`_prefix`](counter.md#symbol-_prefix).
+
+#### `Counter.label` {#symbol-Counter.label}
+
+[source](counter.md#code)
+
+Returns: `string`.
+
+**What it does**
+
+- Return call [`Counter._label`](counter.md#symbol-Counter._label) on `self`.
+
+### `_prefix` {#symbol-_prefix}
+
+[source](counter.md#code)
+
+Private to its defining scope.
+
+Returns: `string`.
+
+**What it does**
+
+- Return `"count"`.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::

package/docs/examples/visibility/index.md

@@ -0,0 +1,33 @@
+---
+title: "Private state and helpers"
+generated: true
+source: "examples/visibility"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+---
+
+# Private state and helpers
+
+Keep underscore-prefixed implementation details inside their scope.
+
+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.
+
+## Project files
+
+- [`main.aug`](main.md)
+- [`counter.aug`](counter.md)
+
+
+## Try this project
+
+From a repository checkout with August installed:
+
+```sh
+aug check examples/visibility
+aug spec examples/visibility
+aug run examples/visibility
+```
+
+[Browse all examples](../index.md)

package/docs/examples/visibility/main.md

@@ -0,0 +1,96 @@
+---
+title: "main.aug · Private state and helpers"
+generated: true
+source: "examples/visibility/main.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `main.aug`
+
+[Private state and helpers](index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](main.md)
+- [`counter.aug`](counter.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+import Counter from counter
+counter = Counter(value=1)
+print(value=counter.label())
+borrow counter:
+    counter.value = 2
+print(value=counter.value)
+```
+
+```aug [Braces]
+import Counter from counter
+counter = Counter(value=1)
+print(value=counter.label())
+borrow counter {
+    counter.value = 2
+}
+print(value=counter.value)
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## Compiled specification {#specification}
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+### In this file
+
+- Run 4 other startup steps in source order.
+
+### Startup, in source order
+
+- Set `counter` to call [`Counter`](counter.md#symbol-Counter) with `value` = `1`.
+- Call `print` with `value` = call [`Counter.label`](counter.md#symbol-Counter.label) on `counter`.
+- Grant exclusive mutable access to `counter` for this block, then end the borrow:
+  - Set `value` of `counter` to `2`.
+- Call `print` with `value` = `value` of `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).
+- Read `value` (`int`); its owner can change it.
+- [`Counter.label`](counter.md#symbol-Counter.label) (no caller inputs) → `string`.
+
+### 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.
+
+::::
+
+:::::

package/docs/examples.json

@@ -0,0 +1,47 @@
+{
+  "readme": {
+    "stdout": "4\n"
+  },
+  "quickstart": {
+    "stdout": "Hello, AugScript!\n"
+  },
+  "generics-guide": {
+    "stdout": "item\nitem\n"
+  },
+  "state-guide": {
+    "stdout": "6\n"
+  },
+  "data-guide": {
+    "stdout": "true\n1\npear\napple\npear\nmissing\n"
+  },
+  "capabilities-guide": {
+    "stdout": "Dependencies are visible\n"
+  },
+  "errors-guide": {
+    "stdout": "No configuration available\n"
+  },
+  "interceptors-guide": {
+    "stdout": "answer\n"
+  },
+  "testing-guide": {
+    "stdout": "3\n",
+    "tests": 4
+  },
+  "class-testing-guide": {
+    "stdout": "1\n",
+    "tests": 2
+  },
+  "ffi-guide": {
+    "stdout": "Hello from C\n"
+  },
+  "spec-guide": {"stdout":"21\n"},
+  "benchmark-startup": {"stdout":"7\n"},
+  "benchmark-cpu": {"stdout":"819677333\n"},
+  "benchmark-collections": {"stdout":"599970000\ntrue\n"},
+  "benchmark-json": {"stdout":"250000\n"},
+  "benchmark-http": {"buildOnly":true},
+  "web-guide": {
+    "buildOnly": true,
+    "tests": 3
+  }
+}

package/docs/getting-started.md

@@ -0,0 +1,5 @@
+# Getting started
+
+```sh
+npx @greenpandastudios/aug-cli@next init hello-august
+```

package/docs/grammar.md

@@ -0,0 +1,136 @@
+# 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.
+
+## Blocks and declarations
+
+```text
+Block       := "{" Statements "}"
+             | ":" NEWLINE INDENT Statements DEDENT
+
+Function    := [Tags] ["fixture"] Name [Generics] "(" Parameters ")"
+               ["returns" ["own"] Type] ["changes" Paths]
+               ["uses" Paths] ["unless" Types] (Block | End)
+
+Class       := [Tags] Name [Generics] ["(" Fields ")"]
+               "implements" Type {"," Type} ClassBlock
+ClassBlock  := BlockOfFieldsAndMethodsWithOptionalInitialize
+Initialize  := "initialize" Block
+
+Record      := "record" Name [Generics] "(" Fields ")"
+               ["unless" Types] [BlockOfInitialize]
+
+Interface   := ("interface" | "capability") Name [Generics]
+               ["extends" Type {"," Type}] Block
+
+Interceptor := "interceptor" Name [Generics] ["(" ResolveFields ")"] Block
+Composition := "composition" Name BlockOfBindings
+Endpoint    := [Tags] "endpoint" HttpMethod String "as" Name "(" Parameters ")"
+               ("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.
+
+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.
+
+```text
+Generics    := "<" Generic {"," Generic} ">"
+Generic     := ["in" | "out"] Name ["implements" Type {"and" Type}]
+Type        := ["optional"] Name ["<" Types ">"]
+Parameter   := ["resolve"] ["mutable"] ["own" | "borrow"] Type Label ["to" Storage]
+               ["from" WireSource [String]]
+Types       := Type {("and" | ",") Type}
+Paths       := Path {("and" | ",") Path}
+Tags        := {"[" Name ["<" Types ">"] ["(" Mappings ")"] "]"}
+Mapping     := AroundLabel ("=" | "to") TargetLabel
+PolicyOption := Name ("=" | "to") (TargetLabel | Literal | ListOfStringLiterals)
+```
+
+Variance is accepted only on interfaces; mutable storage applies to class headers. Resolve cannot be combined with own/borrow. General parameters still use Type name order. Public labels and private storage are explicit in headers.
+
+## Imports, bindings, and calls
+
+```text
+Import      := "import" (Name {"and" Name} | "everything") "from" DottedPath End
+Export      := "export" Name "from" SiblingName End
+             | "export" "folder" ChildName End
+Binding     := "implement" Key ["<" Types ">"] "with" Type
+               ["shared" | "fresh" | "scoped"] ["mutable"] End
+Include     := "include" Name End
+CallInput   := Label ("=" | "to") Expression | Name
+Assignment  := [["own" | "borrow"] Type] Target ("=" | "to") Expression End
+Resolve     := "resolve" Key ["<" Types ">"] "to" Name End
+```
+
+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
+
+```text
+Statement   := Assignment | Expression End | "pass" End
+             | "return" [Expression] End | "throw" Expression End
+             | "if" Expression Block ["else" (Block | If)]
+             | "while" Expression Block
+             | "for" Pattern "in" Expression Block
+             | Pattern ("=" | "to") Expression End
+             | "match" Expression BlockOfCases
+             | "try" Block {"catch" Type Name Block}
+               ["always" Block]
+             | "borrow" Name Block | "unsafe" Block | "scope" Block
+             | "lock" Expression "as" Name Block
+             | "freeze" Expression "as" Name End
+             | "yield" Expression End
+             | "serve" Name {"and" Name} "on port" Expression End
+
+Pattern     := Name | "(" Name {"," Name} [","] ")"
+MatchCase   := "when" ("null" | "some" Name | "true" | "false" | Type Name) Block
+             | "else" Block
+
+Test        := "test" LocalFunction BlockOfGroups
+             | "test" LocalClassType SubjectName BlockOfGroups
+             | "test endpoint" LocalEndpoint ClientName BlockOfGroups
+Group       := "when" TestName BlockOfSetupAndCases
+Case        := "it" TestName ["for" Pattern "in" ListOfTupleRows] Block
+TestName    := Identifier | String
+```
+
+Setup bindings precede setup statements, which precede cases. Empty bodies use pass. Includes are composition/setup operations; declarations and setup ordering are checked beyond parsing.
+
+Optional values have two cases: null and some. Omitted inputs become null. Type? and missing are obsolete spellings; use optional Type and null. Old matches with separate missing and null branches require one merged null branch.
+
+## Expressions and ambiguity
+
+| Spelling | Meaning |
+| --- | --- |
+| `[a, b]` | List literal. |
+| `(a, b)`, `(a,)`, `()` | Tuple literals. |
+| `(a)` | Grouping. |
+| `{a, b}` | Set literal. |
+| `{key: value}` | Map literal. |
+| `{}` | Empty Set or Map determined by context. |
+| `[Validator] header...` | Interceptor annotation on a declaration. |
+| `receiver.member(label=value)` | Labeled method call. |
+| `receiver.member(value)` | Same-name label shorthand when value is a name. |
+| `start load(input=value)` | A scope-owned task. |
+| `wait for first and second` | Ordered task results. |
+| `wait for tasks` | Ordered collection of results. |
+| `handle save(input from form)` | A checked deferred HTTP form action. |
+| `<Panel title={name}>...</Panel>` | Checked server component producing Html. |
+
+Operators from high to low precedence: member/call, unary minus, multiplication/division, addition/subtraction, ordered comparisons, equality, not, and, or. Thus `not count == 0` means `not (count == 0)`. Boolean operations short-circuit from left to right. Only the word spellings are accepted; `&&`, `||`, and unary `!` are syntax errors. `!=` remains accepted. Binary operators associate left. No assignment expression or implicit truthiness is supported. Exponentiation, remainder, and implicit casts are absent.
+
+Function contract clauses may appear in any order, once each; the formatter writes returns, changes, uses, then unless. Storage aliases apply to class/record/interceptor fields rather than ordinary function parameters.
+
+## Newlines, indentation, and comments
+
+- A newline outside delimiters ends a complete statement. EOF and a closing block brace also end it; semicolons may separate same-line statements.
+- An unfinished operator continues onto the next line. Parentheses, lists, tuples, sets, and maps continue until their matching delimiter.
+- A leading operator or call parenthesis on a new line begins a new statement.
+- A colon for a block is followed by a newline and increased indentation. A colon inside a Map literal separates key/value and creates no indentation block.
+- Tabs and spaces are both valid. Mixed characters in one prefix, inconsistent sibling levels, extra unrequested indentation, or a dedent that matches no ancestor are errors.
+- Blank lines and comment-only lines do not alter indentation. // line comments and /* block comments */ are supported.
+- Return expressions begin on the return line; use parentheses to continue one.
+
+The parser owns these rules. The formatter reparses and compares program structure before offering an edit, preserving comments while choosing the project's block and assignment styles.

package/docs/implementation-map.md

@@ -0,0 +1,106 @@
+# Approved language changes — 0.15
+
+## 0.19 additions
+
+Deterministic adjacent source specs, used dependency surfaces with offline links, optional comment requirements, source-package specs, and VS Code preview/generation are described in [compiled specifications](specifications.md). Boolean operators use only `and`, `or`, and `not`; construction uses `initialize` inside declarations. DI uses `implement … with …` and `resolve … to …`; migration is available through the CLI and editor.
+
+## 0.18 additions
+
+- User-authored source packages, public export boundaries, exact npm aliases/local snapshots, transitive dependency scopes and frozen locks are implemented. See [the author/consumer guide](packages.md).
+- Class implementations and private helpers infer capability effects while interface/public function contracts, mutation and checked errors remain explicit. Hover, explain and generated API docs expose inference.
+- [Performance graphs](performance.md) compare verified C/Node/Python workloads, memory and real HTTP throughput. Scaling and lifecycle gaps remain recorded; the measurements do not establish general production readiness.
+- Native scalar lowering retains wrapping integers and checked division, with scalar-only temporaries outside GC roots. Map/Set insertions reuse probes, destructured Map iteration copies fields without per-entry tuple allocation, and HTTP service drains bounded ready batches with coalesced I/O notifications. Behavioral regressions cover generic/default methods, GC, collection mutation and the existing HTTP pipeline.
+
+The original 0.15 map below records the earlier audit delivery.
+
+The September 28 audit recommendations and optional indentation blocks are approved. This map records the delivered implementation, accepted spelling, evidence, and practical limits.
+
+## Syntax
+
+- [x] Colon-led blocks with tabs or spaces, interchangeable with braces; ambiguous indentation rejected and literal braces retained.
+- [x] Canonical formatter, named-import expansion, declaration diagnostics, and [compact grammar](grammar.md).
+- [x] Immutable records and public constructor labels distinct from private storage.
+- [x] Snapshot iteration, tuple destructuring, and checked matching.
+
+Accepted forms: `if ready:`, `record Point(int x, int y)`, `Counter(mutable int initial to _count) implements Count`, `for (key, value) in map`, and `match value: when null: ... when some item: ...`. Class initialization uses an internal `initialize` block. The formatter verifies parsed structure and preserves declaration documentation and wildcard imports.
+
+## Compiler contracts
+
+- [x] Generic invariance, conflict-aware concrete inference, constraints, and checked interface variance.
+- [x] Null narrowing and ownership flow across aliases, nested references, injected call results, branches, and loop re-entry.
+- [x] Pure defaults, changes/uses contracts, interface/interceptor checks, and read-only public/reference access.
+- [x] Header dependencies, pure construction, complete DI graphs, explicit lifetimes/scopes, and shared mutation choices.
+- [x] Recoverable index/arithmetic/conversion failures, specific error contracts, and recovery/propagation fixes.
+
+Accepted forms: `read<T implements Named>(T value)`, `interface Producer<out T>`, `increment() changes self`, `save(resolve FileWriter files) uses files.write unless FileError`, `implement Counter with CounterImpl scoped mutable`, and `scope:`.
+
+Stateful DI defaults to fresh; stateless adapters default to shared. Shared state needs shared mutable. Scope requirements propagate through factories; scoped references cannot escape and shared objects cannot retain them. Local cleanup cannot add effects/errors through layers. Calls forward declared dependencies rather than looking up global services.
+
+## Modules and context
+
+- [x] Import cycles, allowed folder edges, strict sibling surfaces, and optional module/public/wildcard/error lints.
+- [x] Immutable semantic documents and shared built-in/type/inference contracts.
+- [x] Deep seams for dependency ordering, ownership flow, effects, continuation analysis, and interceptor lowering.
+- [x] Explain/context output with provenance, effects, layers, tests, lifetimes, bounded source context, and architecture deltas.
+- [x] Documentation-tag validation, optional public docs warnings, and compiler-checked executable guides.
+- [x] Persistent incremental LSP and local checking while main composition is unfinished.
+
+`main.yaml` configures module_dependencies, strict_modules, lint, and formatter preferences. Explain/context accepts --file, --name, --budget, and --baseline. The VS Code commands display current-file contracts/context beside the source.
+
+### Compiler navigation
+
+| Module | Owned decision |
+| --- | --- |
+| [types.ts](../src/types.ts), [inference.ts](../src/inference.ts) | Type identities and consistent generic unification. |
+| [builtins.ts](../src/builtins.ts) | Built-in labels, types, mutability, errors, docs, and native operation names. |
+| [ownership.ts](../src/ownership.ts), [freshness.ts](../src/freshness.ts) | Object origins, loans, escape, joins, and conservative freshness. |
+| [effects.ts](../src/effects.ts) | Declared mutation/capability contract resolution. |
+| [di.ts](../src/di.ts), [policies.ts](../src/policies.ts) | Graph ordering/cycle paths and module/documentation policy. |
+| [continuation.ts](../src/continuation.ts), [interceptors.ts](../src/interceptors.ts) | At-most-once next analysis, written layer order, input/dependency mapping, and ownership-transfer layout. |
+| [semantic.ts](../src/semantic.ts), [documentation.ts](../src/documentation.ts) | Checked scopes/contracts/provenance and inherited callable documentation. |
+| [lsp.ts](../src/lsp.ts) | Versioned document transport and cached import-closure checks. |
+| [formatter.ts](../src/formatter.ts) | Canonical syntax, comment ownership, and parsed-program equivalence. |
+| [native.ts](../src/native.ts), [config.ts](../src/config.ts) | Native compiler invocation, mapped diagnostics, coverage, timing, and config validation. |
+
+The checker coordinates these modules and still owns core type/body checking. Editor locals come from checked scopes rather than a second syntax-based inference implementation.
+
+## Testing and native runtime
+
+- [x] Same-file function/class suites, independently executed parameter rows, explicit fixtures/compositions, and native coverage.
+- [x] Numeric widths/wrapping, Unicode/NUL behavior, FFI widths, and checked conversion.
+- [x] Check-time config validation, source-mapped native diagnostics, pinned package manifests/lockfiles.
+- [x] Native benchmark workload/report, source metadata, and LLDB adapter/terminal integration.
+
+Accepted forms: `test add:`, `it adds for (left, right, expected) in [(1, 2, 3)]:`, `fixture seven() returns int:`, and `include TestServices` in setup. Coverage is statement-line coverage of the compiled test closure.
+
+The C boundary uses int64_t for int and checked 32-bit C int for c_int. Text is UTF-8 without NUL. [Benchmark measurements](benchmarks.json) include startup and identify the environment.
+
+## Audit coverage
+
+| Findings | Delivered solution |
+| --- | --- |
+| 1, 5, 6, 7, 9 | Pure defaults; declared mutation/capabilities; explicit adapters; pure construction; effective layer contracts. |
+| 2, 3, 4 | Stateful fresh defaults; explicit shared/scoped choices; header DI; complete construction graph and dependency fixes. |
+| 8, 16, 17, 20 | Read-only storage; immutable records; iteration/destructuring/match; public labels/private storage. |
+| 10, 11, 12, 13, 14, 15 | Ownership/null flow; invariance/variance/constraints/inference; checked runtime failures and specific recovery/propagation. |
+| 18, 19, 21, 22, 23 | Named-import expansion; public/module policy; architecture deltas; canonical syntax and precise grammar diagnostics. |
+| 24, 26 | Function/row suites, imported fixtures/compositions, coverage, checked docs, and executable guides. |
+| 25, 27, 28, 29 | Resolved semantics and provenance; shared registries; deep compiler seams; bounded context and cached persistent LSP. |
+| 30 | Defined numeric/text/ABI behavior; config/native diagnostics; benchmark evidence; source maps/debug launch; pinned dependencies. |
+
+## Verification
+
+- [x] All 16 bundled projects migrated, checked, formatted idempotently, and run natively; their six built-in cases pass.
+- [x] Eleven complete guide projects compile/run, with six documented test cases and unchanged native behavior after formatting.
+- [x] Regressions cover successful and rejected contracts, versioned LSP caching, concrete quick-fix edits, zero-count coverage, source diagnostics, and cleanup paths.
+- [x] Final TypeScript/compiler gate: type checking and all 156 regression tests pass.
+
+The VS Code release is 0.15.0. Its package includes the compiler, runtime, source examples, and these guides; build artifacts are excluded. Use the repository packaging/install commands in README.md.
+
+### Current limits
+
+Ownership and short-circuit descriptions are conservative analyses rather than formal proofs. The LSP caches parsed modules and checked import closures, not individual expressions. Coverage counts statement lines, not branches; startup is excluded from tests.
+
+LLDB resolves AugScript source breakpoints. Its launch smoke test stalled on this host and was stopped; interactive stepping/call stacks remain unverified here. The VS Code DAP path requires lldb-dap, which is not installed on this machine. Native tagged-value variable views need further debugger work.
+
+Benchmarks establish only the measured workload on this host; no universal speed or Python/Rust comparison is claimed. Threads, binary/pointer-heavy FFI, and a package resolver remain deferred as agreed. Clock/random/network capabilities can follow the same explicit-capability contract when those APIs are added.

package/docs/index.md

@@ -0,0 +1,46 @@
+---
+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.
+  actions:
+    - theme: brand
+      text: Build your first project
+      link: /getting-started
+    - 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.
+---
+
+## Documentation for the code you run
+
+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.
+
+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.
+
+## Why August
+
+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.
+
+## Performance and readiness
+
+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. [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.

package/docs/language-conformance.md

@@ -0,0 +1,30 @@
+# 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.
+
+## What the compiler guarantees
+
+| Rule | Developer-visible behavior | Conformance case |
+| --- | --- | --- |
+| Owned moves | Passing an `own` value to an `own` input or `Shared(value=...)` consumes the old name. A second use is a compile error. A value borrowed by a child cannot move through a call, another `Shared<T>`, a local declaration, a return, or a throw until the child finishes. | `OWN-1`, `SHARED-1`, `TASK-8`, `TASK-11` through `TASK-13`, `TASK-17` |
+| Mutable access | Reading through another alias during `borrow` is a compile error. The alias can be read again after the block. | `BORROW-1` |
+| Child captures | A child can read a managed object without copying it. The parent must wait before mutating that object through any alias, borrowed call, or field write. This applies even when the parent opened `borrow` before starting the child. Every possible branch must wait before mutation resumes. Freezing also waits for active mutable access. | `TASK-1` through `TASK-4`, `TASK-10`, `TASK-14` |
+| Repeated starts | A `start` inside a loop can create several children. Waiting for one result does not release captures from other iterations; the enclosing `scope` joins them all. Put a `scope` inside the loop when each iteration should release its capture before the next iteration. | `TASK-7`, `TASK-15`, `TASK-16` |
+| Collection waits | Waiting for one dynamically selected `Task<T>` does not release captures from other tasks that might be selected. A task that holds a reference to another task also cannot release that task's capture when only the first is awaited. `wait for` a `List<Task<T>>` joins every child in the list and releases their captures. | `TASK-18`, `TASK-19` |
+| Checked child errors | Starting a child checks errors in its argument expressions. An error from the scheduled operation is checked at `wait for` or at the implicit scope join. Within the same scope, the checker knows the child's declared errors. A helper given a public `Task<T>` parameter handles or declares `Error`, since that type does not carry a narrower error list. | `ERROR-1`, `ERROR-3` |
+
+The compiler tracks object origins through aliases and fields. It can reject code when it cannot prove that two references are separate. [The language guide](reference.md#ownership-and-read-access) explains `own`, `borrow`, `freeze`, and `Shared<T>`.
+
+## What native execution guarantees
+
+| Rule | Developer-visible behavior | Conformance case |
+| --- | --- | --- |
+| Owned cleanup | An owned local is dropped once after normal scope exit or a checked error. Moving it transfers that responsibility. An owned `Shared<T>` drops its transferred payload. | `OWN-1`, `OWN-2`, `SHARED-1` |
+| Scope exit | Leaving a scope, including by `return`, joins its children before the caller resumes and before the scope releases owned dependencies. An inner scope's join releases its capture for later outer code. Captured resources remain live through collection pressure and drop once after the join. | `CLEANUP-2`, `TASK-5`, `TASK-6`; [resource join test](../tests/concurrency.test.mjs) |
+| `always` | Cleanup runs before a returned result is observed and while a cancelled child unwinds. | `CLEANUP-1`, `CANCEL-1` |
+| Child failure | An unhandled child failure cancels siblings. Their `always` cleanup finishes before the error leaves the scope. An error already in flight from the parent remains primary if child cleanup also fails. | `CANCEL-1`, `ERROR-2` |
+| Syntax choice | Brace blocks and indented blocks run the same ownership and task behavior. | `SYNTAX-1` |
+
+Tasks currently run cooperatively on one OS thread. A long loop reaches cancellation at compiler-inserted checkpoints. `Shared<T>` is the explicit path for synchronized mutable state. The runtime does not yet promise parallel CPU execution.
+
+Run the focused suite with `node --test tests/language-conformance.test.mjs`. The full repository test command also runs existing [concurrency](../tests/concurrency.test.mjs), ownership, errors, formatter, and generated-spec tests. This suite is growing through adversarial review; a green run does not establish complete ownership safety. The [roadmap](roadmap.md) keeps the language semantics gate open until that review and native CI finish.