@greenpandastudios/aug-cli 0.19.0

package/docs/reference.md

@@ -0,0 +1,361 @@
+# AugScript language guide
+
+Version 0.18. The language aims for code that communicates behavior, dependencies, and effects to a developer seeing a module for the first time.
+
+## A complete project
+
+`main.aug` contains imports, dependency bindings, and startup statements. Declarations live in other files. Every file has its own import scope.
+
+```aug project=quickstart file=main.aug
+import Console and SystemConsole from august.io
+import Application from app
+
+implement Console with SystemConsole
+implement app with Application
+
+resolve app to program
+program.start()
+```
+
+```aug project=quickstart file=app.aug
+import Console from august.io
+
+/** The application's startup behavior. */
+interface Runnable:
+    start() uses Console.write
+
+/** Construction receives dependencies and performs no I/O. */
+Application(resolve Console console) implements Runnable:
+    start():
+        console.write(value="Hello, AugScript!")
+```
+
+Run `node bin/aug.mjs run PROJECT`, or choose **AugScript: Run Project** in VS Code. Node.js 24+ and a C11 compiler are required.
+
+## Blocks and statement boundaries
+
+Either spelling creates the same block:
+
+```text
+if ready {
+    work()
+}
+
+if ready:
+    work()
+```
+
+A colon must be followed by a newline and an indented body. Use a consistent spaces-only or tabs-only prefix within each indentation region. Nested regions must agree with their parent's prefix. Blank lines and comment-only lines do not create blocks. Misaligned dedents, extra indentation, and mixed prefixes are errors. Braced children can appear in an indented block.
+
+Parentheses and collection literals allow continuation across lines; their indentation does not create a statement block. Literal `{1, 2}` and `{1: "apple"}` retain their meaning. `pass` is an empty statement, useful for empty interfaces and bodies.
+
+A newline, a closing block brace, EOF, or an optional semicolon terminates a statement. Separate two statements on one line with a semicolon. An unfinished operator continues an expression; a leading operator or call parenthesis on a new line does not attach to the previous statement. Start a return value on the same line as `return`. See [the grammar](grammar.md).
+
+Use `and`, `or`, and `not` for booleans. They short-circuit. Comparisons bind before `not`: `not count == 0` means `not (count == 0)`. The symbolic boolean operators are rejected; `!=` still compares for inequality.
+
+## Imports and visibility
+
+`import Name from sibling` imports only that sibling's own public declaration. Imports are explicit even within a folder. Names beginning with `_` are private to their declaring file, class, or interface, and cannot be imported or exported.
+
+A folder's public surface is defined by its special `export.aug`:
+
+```text
+export Logger from logger
+export ConsoleLogger from console
+export folder nested
+```
+
+Cross-folder access requires the export entry. A dotted path also requires each crossed child folder to be exposed by its parent. A folder with no export file exposes nothing across its boundary. `export.aug` accepts only exports. Private modules and folders cannot be exported.
+
+`import Logger and ConsoleLogger from logging` combines imports. `import everything from logging` imports visible declarations and rejects collisions; it never exposes a module's internal imports. The formatter preserves it. Hover shows available names, **Expand to named imports** offers an explicit list, and the [compiled spec](specifications.md) explains dependencies actually used.
+
+Import cycles are errors. Optional module dependency policies and public-surface warnings are configured in `main.yaml`. `strict_modules: true` also requires sibling imports to appear in the local export file. Ctrl-click `from` or a path segment to open its source file or export file, including `august.io`.
+
+Project dependencies use aliases in `main.yaml`: `packages: math: "npm:@owner/aug-math@1.2.3"` as a nested YAML block. Run `aug install`, then write `import add from math`. A library exposes only its source folder's `export.aug`; internal modules and undeclared transitive dependencies are inaccessible. See [creating and using packages](packages.md#author-a-package).
+
+## Types, labels, and generics
+
+Built-in types include `int`, `c_int`, `float`, `bool`, `string`, `void`, `Error`, runtime error classes, `List<T>`, `Set<T>`, `Map<K,V>`, `Tuple<T1,...>`, Bytes, Json, Html, Task<T>, Shared<T>, HttpRequest, HttpResponse<T>, ServerEvent<T>, and opaque RSA key types. `optional T` allows a value of T or null. Omitted optional inputs and fields become null; there is no separate missing state. `Type?`, `optional Type?`, and the old missing keyword are rejected.
+
+Write `Type name = expression`, `Type name to expression`, or an inferred assignment. Every ordinary input in a call has its public label: `add(right=2, left=1)`. Each label is supplied once. Inputs marked `resolve` are supplied through composition and cannot be passed explicitly.
+
+User generics are invariant by default. Inference must produce a concrete, consistent type; repeated occurrences of a type parameter cannot disagree. Empty literals can infer from other labeled arguments. Explicit arguments remain available when inference has no evidence.
+
+```aug project=generics-guide file=main.aug
+import Item and describe and Holder and Named and Producer from types
+
+print(value=describe(value=Item()))
+Producer<Named> item = Holder(value=Item())
+print(value=item.get().name())
+```
+
+```aug project=generics-guide file=types.aug
+interface Named:
+    name() returns string
+
+Item() implements Named:
+    name() returns string:
+        return "item"
+
+describe<T implements Named>(T value) returns string:
+    return value.name()
+
+interface Producer<out T>:
+    get() returns T
+
+Holder<T>(T value) implements Producer<T>:
+    get() returns T:
+        return value
+```
+
+Constraints name interfaces. Multiple constraints use `and`. Only interfaces declare `out T` or `in T`; the compiler checks every occurrence, including inherited members. Classes, records, and mutable collections remain invariant. Generic DI keys must be concrete, such as `Repository<int>`.
+
+## Classes, records, and local state
+
+A class starts with its name and ends its header with `implements Interface`. There is no `class` or `function` prefix and no class inheritance. Interfaces can extend several interfaces and supply default methods; conflicting inherited defaults require an explicit override. Interfaces have methods and no fields.
+
+Header inputs become fields. Fields are read-only after initialization unless marked `mutable`. Public names grant access; names starting with `_` keep storage private. Separate a public constructor label from private storage with `int initial to _count`. The shorthand `int _count` exposes the input label `count`.
+
+```aug project=state-guide file=main.aug
+import Counter from counter
+
+counter to Counter(initial=4)
+borrow counter:
+    counter.increment()
+print(value=counter.value())
+```
+
+```aug project=state-guide file=counter.aug
+interface Count:
+    increment() changes self
+    value() returns int
+
+Counter(mutable int initial to _count) implements Count:
+    initialize:
+        _count = _count + 1
+    increment() changes self:
+        _count = _count + 1
+    value() returns int:
+        return _count
+```
+
+The optional `initialize` block runs after header and local field initialization and must be pure. It may establish local fields. Put it before methods. Put external startup work in a named method and call it from main.
+
+An immutable record is data and needs no marker interface:
+
+```aug project=data-guide file=main.aug
+import Point from data
+
+point = Point(y=2, x=1)
+print(value=point == Point(x=1, y=2))
+print(value={point, Point(x=1, y=2)}.length())
+(first, second) = (1, "pear")
+print(value=second)
+
+for (key, value) in {1: "apple", 2: "pear"}:
+    print(value=value)
+
+Map<int, string> fruit = {1: "apple"}
+match fruit.get(key=7):
+    when null:
+        print(value="missing")
+    when some name:
+        print(value=name)
+```
+
+```aug project=data-guide file=data.aug
+record Point(int x, int y)
+```
+
+Record fields contain primitives, tuples, and immutable records. They cannot store mutable collections, capabilities, or ownership inputs. Records compare and hash by type and field values. Validation uses `record Positive(int value) unless DomainError { initialize { ... } }`; it may reject an input, and cannot replace immutable fields. Behavioral classes compare by identity.
+
+## Collections and iteration
+
+| Literal | Type | Behavior |
+| --- | --- | --- |
+| `[1, 2]` | `List<int>` | Ordered, mutable elements. |
+| `(1, 2)` | `Tuple<int,int>` | Fixed positions; `(1,)` is a singleton. |
+| `{1, 2}` | `Set<int>` | Unique elements with hashing. |
+| `{1: "apples", 2: "pears"}` | `Map<int,string>` | Hashed keys; the last duplicate key wins. |
+
+Empty literals require context: `List<int> values = []`, `Set<int> values = {}`, or `Map<int,string> values = {}`. Typed declarations require a variable name. Mixed integer/float literals widen to float. A tuple can contain different types. `(1)` is grouping and `()` is an empty tuple.
+
+| Type | Reading | Mutation |
+| --- | --- | --- |
+| List | `length()`, `get(index=...)` unless IndexError, `at(index=...)` returns T? | `append(value=...)` |
+| Set | `length()`, `contains(value=...)` | `add(value=...)` |
+| Map | `length()`, `contains(key=...)`, `get(key=...)` returns V? | `set(key=..., value=...)` |
+| Tuple | `length()`, `get(index=constant)` with compile-time bounds | None |
+
+Managed mutations need a borrow; owned collections mutate directly. Collections cannot store borrowed or owned references by copying them. Reference results grant reading.
+
+Tuple destructuring introduces new local names and checks arity. `for item in values` snapshots List, Set, and homogeneous Tuple elements. `for (key, value) in map` snapshots entries in insertion order. Modifying the original collection does not extend the current iteration. Reference elements remain read-only.
+
+## Functions, effects, and capabilities
+
+A bare header without `implements` declares a function. Omitting `returns` means void. Non-void bodies must return or throw on every path. A bodyless top-level declaration cannot be called unless it is an extern declaration.
+
+Public standalone functions and interface contracts are pure unless they declare capabilities. State transitions declare `changes self` or `changes input`; mutable reference inputs require `borrow` or `own`. A helper cannot mutate a managed input, an alias, or nested objects reachable through it.
+
+I/O uses capability interfaces and checked `uses dependency.operation` contracts. Capability types have interface behavior and permit explicit adapter substitution. The standard `august.io` folder provides Console/SystemConsole, FileReader/FileWriter/LocalFiles, and Arguments/ProcessArguments.
+
+```aug project=capabilities-guide file=main.aug
+import Console and SystemConsole from august.io
+import announce from messages
+
+implement Console with SystemConsole
+announce(message="Dependencies are visible")
+```
+
+```aug project=capabilities-guide file=messages.aug
+import Console from august.io
+
+announce(resolve Console console, string message) uses console.write:
+    console.write(value=message)
+```
+
+A caller's contract must include the effects of its calls and interceptor layers. Interface implementations cannot add mutation or effects beyond the interface contract. A contract may name `Console.write` when a concrete dependency is exposed through another interface.
+
+### Short implementation headers
+
+Class methods and private `_helpers` infer `uses` when it is omitted. Interfaces, public standalone functions, interface default methods, and interceptor `around` methods retain explicit effect contracts. An explicit `uses` clause is an upper bound, including on implementations. `changes` and `unless` are still explicit.
+
+```text
+import Console from august.io
+
+interface Logger:
+    log(string message) uses Console.write
+
+ConsoleLogger(resolve Console console) implements Logger:
+    log(string message):
+        _write(console, message)
+
+_write(Console console, string message):
+    console.write(value=message)
+```
+
+Both bodies infer `Console.write`; the interface states it once. Inference follows calls, generic substitutions and interceptor layers to a fixed point, so declaration order does not matter. Hover and `aug explain` show inferred capabilities; generated library API pages include them. Calling an inferred helper from a pure public function is a compile error. A pure interface cannot acquire hidden I/O through its implementation.
+
+Capability implementations inherit their operation contract even when a test adapter does no I/O. This includes shared-state capabilities such as `ExpiringStore<T>`. Constructors and `drop()` remain pure; inference does not permit I/O while holding a lock. Type-changing recursive generic effect inference that cannot converge requires an explicit finite `uses` clause.
+
+Outside main and test setup, every injected dependency is declared in the callable/class header. Calls forward the one compatible header dependency; multiple candidates require a clearer header. Constructor and interceptor dependencies are checked the same way. Body-level `resolve` is rejected with a fix to lift it into the header.
+
+Raw `print`, `arguments`, `read_file`, and `write_file` are available to main/test tooling and the trusted standard adapters. Other callables receive explicit capabilities. Pure construction cannot perform these effects.
+
+## Dependency injection and lifetimes
+
+Provide one implementation per key before startup: `implement Logger with ConsoleLogger`. A named key such as `app` selects a class without a type key. `resolve app to program` retrieves it explicitly. Legacy `bind` and assignment-form resolve are rejected; use `aug migrate` or the editor migration fix.
+
+A bound class must have only `resolve` header inputs. Duplicate bindings, missing dependencies, cycles, incompatible keys, and effectful bound construction are errors. Diagnostics show the dependency path. Declaration order does not determine initialization order.
+
+| Lifetime | Meaning |
+| --- | --- |
+| `shared` | One eagerly constructed instance per composition. Default for stateless adapters. |
+| `fresh` | Construct on each resolve. Default for stateful classes. |
+| `scoped` | Cache inside an explicit `scope` block; nested scopes have their own cache and restore the outer cache. |
+
+Statefulness includes mutable fields, owned mutable storage, `changes self` methods, and retained stateful dependencies. Process-wide state requires `shared mutable`. Stateful scoped bindings use `scoped mutable`. Scoped dependencies require a scope even through fresh factories; shared objects cannot retain them.
+
+A scoped reference cannot escape into an outer variable, a return, or longer-lived storage. A first-class `composition Services { implement ... }` collects bindings in an explicitly imported module. Main or test setup uses `include Services` before execution. There is one root and no implicit registration.
+
+See [the scoped composition example](../examples/approved-design/counters.aug).
+
+## Ownership and read access
+
+Default objects are managed and reclaimed by the runtime. Ordinary reads require no borrow. An `own` value has exclusive lifetime control; passing it to an own input, field, or return moves it. Using a moved value or copying it into managed storage is rejected.
+
+`borrow value { ... }` or its colon form grants exclusive mutable access. A `borrow Type input` grants it for the call. The compiler tracks aliases, nested references, binding identities, call inputs/results, branch joins, escaping loans, and loop re-entry. Ordinary managed inputs and public reference reads are deep read-only views.
+
+Owned values are dropped on normal or error exits. An optional `drop()` method takes no inputs, returns void, and performs only local cleanup. Cleanup layers cannot add effects or errors. External shutdown work belongs in an explicit effect-declared method. Managed objects are collected at runtime safe points; process roots survive to shutdown.
+
+`Shared(value=...)` takes a fresh or owned value. The wrapper owns that payload, so dropping an owned `Shared<T>` also runs the payload's `drop()` before later local cleanup. A `resolve` dependency counts as a call input for alias checks: it cannot refer to an object also passed as an exclusive input. A scheduled task captures dependencies supplied through `resolve` as well as written call arguments. Wait for a task before mutably borrowing an object it reads through either path.
+
+A child borrowing an owned `Shared<T>` pins the wrapper until the child finishes. The parent cannot transfer it to another owner, put it in another `Shared<T>`, or return it while the child uses it. A child can still read a `Shared<T>` concurrently through its own reference. Use `lock` to access the payload.
+
+If a child starts while a `borrow` block is already open, the parent cannot mutate the captured object until it waits. The rule also applies to a borrowed function call or a direct field assignment. See the [executable conformance rules](language-conformance.md).
+
+If `start` runs inside a loop, a wait for one result may leave children from earlier iterations running. Their captures remain pinned until the enclosing `scope` joins them. To release captures on each iteration, put a `scope` inside the loop and finish its children there.
+
+For a collection of tasks, `wait for tasks` joins the whole list. Waiting for one task selected with a dynamic index cannot prove which sibling tasks remain active, so their captures stay pinned until the scope joins them.
+
+The analysis intentionally rejects some programs when it cannot prove separate origins or freshness. This prototype is conservative; it is not a formal ownership proof. Threading semantics remain deferred.
+
+## Null, matching, and checked failures
+
+Nullable locals narrow after null checks, short-circuit conditions, match patterns, and surviving early-return branches. Mutable fields are narrowed conservatively.
+
+`match value` uses `when null`, `when some name`, `when true`, `when false`, or `when Type name`. Nullable and bool matches must cover every case. Open class/interface domains require `else`. Duplicate/unreachable cases and incompatible patterns are errors.
+
+An error satisfies Error. A callable declares specific errors with `returns T unless FileError and DomainError`. It can throw any value satisfying its declaration; declaring Error accepts any Error implementation. Calls must catch or propagate all effective errors, including interceptor layers.
+
+`start` evaluates its receiver and arguments immediately; their errors belong to the scheduling statement. The scheduled operation's errors belong to a `wait for` or its owning scope's implicit join. Unobserved sibling failures can reach any wait in that group. Grouped waits observe every selected child, including cancellation cleanup, and rethrow the first failure. A helper awaiting a `Task<T>` parameter declares or handles `Error`, since that public type does not specify a narrower error contract yet.
+
+An error already leaving the parent remains the reported error if cancelling a child causes its cleanup to fail. `always` cleanup still runs for that child. A `return` from a scope joins its children before the caller receives the result.
+
+```aug project=errors-guide file=main.aug
+import load from files
+import FileReader and LocalFiles from august.io
+
+implement FileReader with LocalFiles
+try:
+    print(value=load(path="definitely-missing.txt"))
+catch FileError error:
+    print(value="No configuration available")
+```
+
+```aug project=errors-guide file=files.aug
+import FileReader from august.io
+
+/**
+ * Read a configuration file.
+ * @param path File path.
+ * @return UTF-8 text.
+ * @throws FileError Reading failed or the text is invalid.
+ */
+load(resolve FileReader files, string path) returns string uses files.read unless FileError:
+    return files.read(path=path)
+```
+
+List.get raises IndexError; List.at returns null. Division by a potentially zero value requires ArithmeticError handling. Literal nonzero divisors need no error clause. Runtime invariant corruption and allocation failure remain fatal.
+
+Quick Fix offers propagation through `unless` or an explicit recovery template. Optional lints flag broad Error contracts and discarded errors. The internal diagnostic code for unchecked failures remains THROWS; the language spelling is `unless`.
+
+## Interceptors
+
+A first-class `interceptor` wraps a function, method, or constructor. It defines one implemented `around`, may have helper methods and resolve dependencies, and needs no interface.
+
+```aug project=interceptors-guide file=main.aug
+import describe from descriptions
+
+print(value=describe(x=4, label="answer"))
+```
+
+```aug project=interceptors-guide file=descriptions.aug
+interceptor AddOne<T>:
+    around(int y) returns T:
+        return next(y=y + 1)
+
+[AddOne(y=x)]
+describe(int x, string label) returns string:
+    return label
+```
+
+Around selects only the target inputs it needs. Labels match automatically; `[Validator(y=x)]` maps target x to around y. Resolve inputs are declared dependencies, never mappings. Types, ownership, effects, errors, and results are checked. Generic arguments can be inferred or supplied.
+
+Layers execute in written order; the first is outermost. `next()` forwards original inputs to the next layer or target. Labeled overrides change mapped inputs, while unselected inputs pass through. Each path calls next at most once. A layer can deliberately short-circuit with a compatible result or error.
+
+Every layer dependency must appear in the target's header dependencies; registration is explicit. Constructor layers must be pure. Callable hover and explain/context output show layer order, dependency origins, added effects/errors, delegation, and possible short-circuiting.
+
+See [the complete validation and testing example](../examples/approved-design/domain/numbers.aug).
+
+## Documentation, tests, and tooling
+
+Javadoc immediately before a declaration feeds hover, completion, and signature help. Supported tags include `@param`, `@return`, `@throws`/`@exception`, `@see`, and `@deprecated`; `{@code ...}` and `{@link ...}` format inline help. Parameter labels, return tags, and effective error tags are checked; mismatches are DOC errors. Implementations can inherit interface method documentation.
+
+`aug spec` compiles each file's complete behavior into an adjacent Markdown explanation. Comments are optional unless `main.yaml` sets `spec.require_comments` to `public` or `all`. See [compiled specifications](specifications.md).
+
+Enable the public_docs lint for missing public descriptions. Keep behavior examples in [same-file class or function suites](testing.md). [Explain/context](tooling.md#context-for-developers-and-llms) gathers contracts and provenance with a bounded output budget. The persistent editor server checks local modules while an application root is unfinished; complete composition remains a build gate.
+
+Numeric widths, Unicode behavior, FFI, configuration, debugging, benchmarks, and CLI output are specified in [the tooling guide](tooling.md).
+
+First-party endpoints, wire inputs, HTTP policies, streams, server components and actions, scoped tasks, OpenAPI, endpoint tests and cryptographic capabilities are specified in the [web guide](web.md). The [same-app login proof](../examples/oidc-login/README.md) demonstrates these features through an OpenID Connect provider and client in one executable.

package/docs/release-review.md

@@ -0,0 +1,23 @@
+# August web release review
+
+Reviewed on 2026-09-28 against [the confirmed implementation plan](web-implementation-plan.md). The repository had no existing commit, so the initial implementation was reviewed as a whole. Independent Standards and Spec reviewers performed follow-up checks after fixes. Compiler, native socket, browser transport, and same-file endpoint regressions verify the runtime behavior.
+
+## Standards
+
+All six original invariant findings are addressed: duplicate input safety, inherited child cancellation/deadlines, lock progress, owned capture lifetime, delayed checked errors, and response status errors. Follow-up fixes narrow cleanup to the explicit scope boundary, check possible sibling failures at waits, and observe all selected children during failed grouped waits. No concrete new defects were found in the final narrow review.
+
+Policy emission now uses named native identifiers instead of duplicated numeric ordering.
+
+## Spec
+
+All five original and two follow-up findings are addressed: malformed duplicate inputs, cancellation while awaiting children, lossless int64 action values, complex typed forms, empty endpoint-test streams, string-valued Json form encoding, and post-yield failures in endpoint tests. No new defects were found in the final narrow review.
+
+## Verification
+
+`npm run check` passes. The final full `npm test` run passes all 185 tests, including native HTTP/1.1, TLS HTTP/2 and HTTP/3, independent signature verification, and the same-application OpenID Connect login/session/logout flow.
+
+## Remaining scope
+
+See [the gap ledger](web-library-gaps.md). Multicore worker and channel/broadcast changes were rejected by automatic approval review and have not been applied; explicit approval requests remain pending. This release uses cooperative scheduling on one OS thread. Broader HTTP and OpenID Connect certification, persistent accounts, federation, key rotation, inbound streams, and other recorded follow-up capabilities remain outside the verified proof.
+
+Final review: Standards 0 unresolved findings; Spec 0 unresolved findings within the implemented scope. Pending approval scope remains incomplete.

package/docs/releasing.md

@@ -0,0 +1,79 @@
+# Releasing August
+
+All first-party packages and the extension use one compiler-compatible version. npm manifests live in `packages`; canonical code remains in `src` and `runtime`.
+
+## Verify and create artifacts
+
+```sh
+node scripts/version.mjs 0.19.0
+npm ci
+npm --prefix vscode ci
+node scripts/bootstrap-native.mjs
+npm run version:check
+npm run check
+npm test
+npm run docs:check
+npm run docs:build
+npm run package:packages
+npm run test:packages -- --native
+npm run package:extension
+node scripts/release-artifacts.mjs
+```
+
+Update both changelogs and relevant guides, and commit regenerated docs. The final artifact step combines four installable npm tarballs, a VSIX, offline documentation, package metadata and SHA-256 checksums under `dist/release`. It excludes native caches, private credentials and application build output.
+
+## GitHub release
+
+After verification and committing, create and push the version tag:
+
+```sh
+git tag v0.19.0
+git push origin main v0.19.0
+```
+
+`release.yml` validates the tag against every manifest, runs compiler/native/docs/package gates, and uploads artifacts to a **draft prerelease**. Review the draft and publish it in GitHub Releases. `ci.yml` checks pushes and pull requests. Linux CI builds the pinned full native stack, runs the native suite, and executes core and crypto apps in the matching runtime image. macOS CI runs the same native suite with its private bootstrap.
+
+## npm publication
+
+The intended scope is `@greenpandastudios`. Claim this npm identity or choose an owned scope consistently before the first registry release. Create the initial packages with the owner's authenticated npm account. GitHub tarballs work independently of registry setup.
+
+Configure a trusted publisher for each of the four npm packages:
+
+- Owner: `GreenPandaStudios`
+- Repository: `augscript`
+- Workflow filename: `publish-npm.yml`
+- Environment: `npm`
+- Allowed action: `npm publish` (new configurations default to stage publishing)
+
+Use npm CLI 11.5.1+ and GitHub-hosted runners. The workflow grants `id-token: write` for OIDC and needs no stored npm publishing token. Match package repository URLs to this repository. See [npm's trusted publisher instructions](https://docs.npmjs.com/trusted-publishers/).
+
+Publishing a reviewed GitHub release automatically runs **Publish npm packages**. To retry, dispatch that workflow with the existing verified version tag. It checks out that tag, checks types/docs/installed artifacts, then publishes standard library, web, crypto and CLI in dependency order with public access and the `next` dist tag. The `npm` environment can hold owner-configured release protection. Existing versions cannot be overwritten; inspect partial runs before retrying.
+
+## VS Code Marketplace
+
+Confirm ownership of the `augscript` Marketplace publisher. Publishing a reviewed GitHub release runs **Publish VS Code extension** (`publish-marketplace.yml`); manual dispatch accepts the same published tag for retries. It downloads the release's VSIX, verifies its SHA-256 checksum, version and `augscript.augscript` identity, then publishes that exact artifact. VSIX files remain available directly from GitHub Releases.
+
+One-time owner setup follows [Microsoft's secure publishing guide](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#secure-automated-publishing-to-visual-studio-marketplace):
+
+- Create a Microsoft Entra identity and grant it publishing access to the `augscript` Marketplace publisher.
+- Add a GitHub federated credential with issuer `https://token.actions.githubusercontent.com`, audience `api://AzureADTokenExchange`, and subject `repo:GreenPandaStudios/augscript:environment:marketplace`.
+- Create the GitHub environment `marketplace` and set its variables `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` to that identity's IDs. Configure release protection there if needed.
+
+The workflow uses Azure login through OIDC and the pinned `vsce` CLI's `--azure-credential` support. No publishing token is stored. The first public listing requires the publisher identity setup; the repository does not establish ownership of a Marketplace namespace. The intended listing is [AugScript](https://marketplace.visualstudio.com/items?itemName=augscript.augscript), currently unpublished.
+
+The packaging script supplies the repository's `vscode` directory as the HTTPS
+base for README images. Verify those URLs are public before Marketplace
+publication; a private or not-yet-created repository cannot serve them to other
+users. The extension logo and **AugScript: Open Welcome** images are bundled
+locally and do not depend on that image host. To update artwork, run
+`npm --prefix vscode run artwork` and commit the rendered PNGs.
+
+Global Azure DevOps PATs retire on December 1, 2026; this project does not introduce a new long-lived Marketplace PAT. Marketplace identity setup is an external owner prerequisite.
+
+## Documentation deployment
+
+Enable GitHub Pages with **GitHub Actions** as its publishing source. `docs.yml` checks generated pages, builds the same Markdown and deploys through the `github-pages` environment after successful CI on main. Private repositories need an eligible GitHub plan for Pages. Docs remain readable in the repo and offline artifact when Pages is unavailable. See [GitHub's workflow requirements](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages).
+
+## Current limits
+
+August is experimental. Native web/crypto bootstrap supports macOS and Linux; other platforms are unverified. Registry and Marketplace identities require owner configuration. User-authored source packages are supported through npm transport; prebuilt native dependency releases and a stable external native adapter ABI remain future work. See [the gap ledger](web-library-gaps.md) and [performance assessment](performance.md).

package/docs/roadmap.md

@@ -0,0 +1,13 @@
+# Roadmap to 1.0.0
+
+August's goal is a language that stays understandable as a codebase grows: local context, explicit public surfaces and dependencies, checked errors, and generated explanations that match the executable code. This roadmap covers the language, its native toolchain, and developer distribution. It uses evidence gates, not a speculative release date.
+
+| Stage | Work | Exit evidence |
+| --- | --- | --- |
+| 0.19: public preview | Runnable CLI, editor, source packages, wiki, same-file tests, specs, measured benchmarks, and starter projects. | Current CI and [example projects](examples/index.md); experimental label remains. |
+| 0.x: language and ownership | Define and check mutable captures, shared object lifetime, cleanup, delayed errors, and task cancellation for the documented cooperative task model; keep both block styles and specs in sync. | **Open:** the [ownership and task conformance suite](language-conformance.md) covers moves, aliases, branch and nested-scope joins, initialization, return/error exits, collection pressure, and public `Task<T>` errors. [Generated robustness checks](production-readiness.md#what-is-measured-and-verified) now exercise parser recovery, native results, and the core runtime under sanitizers. Adversarial review found additional capture and lifetime gaps after the first green CI run; independent review and wider runtime coverage remain before this gate can close. |
+| 0.x: portable native stack | Reproducible Linux and macOS web/crypto builds; build/run container images for full apps; platform-specific CI. | Versioned dependency manifests, license notices, native integration tests, and matching package builds on each target. |
+| 0.x: developer distribution | Publish version-matched npm packages and VS Code extension; project bootstrap with `npx`; package compatibility and reproducible releases. | Clean installed-package tests, signed/versioned artifacts, release instructions, and supported upgrade path. |
+| 1.0.0 | Freeze the supported language and package/native ABI; publish migration policy and production support matrix. | All preceding gates pass in CI, examples and specs regenerate deterministically, dependency audit and security review pass, and known gaps are classified explicitly. |
+
+HTTP and OIDC hardening are library and application work. They are tracked in the [web and crypto gap ledger](web-library-gaps.md) and are not gates for the language's 1.0 release. The [compatibility policy](compatibility.md) identifies the proposed 1.x contract and platform evidence still required. The [production readiness page](production-readiness.md) explains current use and dependency obligations. Language performance is tracked with [reproducible benchmarks](performance.md), with regressions investigated before a stable release.

package/docs/specifications.md

@@ -0,0 +1,86 @@
+# Read the compiled specification
+
+August keeps explanations beside the code. `aug spec` compiles each checked source file into a neighboring Markdown file. It describes the code without running the application or sending it to a model.
+
+[See complete example projects](examples/index.md) with highlighted source in either indentation or braces style and the actual compiled spec for every file.
+
+```sh
+aug spec .
+aug spec . --check
+```
+
+| Source | Explanation |
+| --- | --- |
+| `main.aug` | `main.aug.md`: providers and startup operations. |
+| `orders.aug` | `orders.aug.md`: contracts, local behavior, helpers, and tests. |
+| `export.aug` | `export.aug.md`: the folder's public surface. |
+| An installed dependency | A versioned explanation and source copy under `.aug-spec/`. |
+
+Successful `build`, `run`, and `bench` commands refresh these documents after native compilation. `aug pack` refreshes them before creating the source archive. `--check` writes nothing and exits with a failure if a document, dependency copy, or manifest is missing or stale. Use it in CI after `aug check`.
+
+## What the document explains
+
+The compiler describes labeled inputs, injected dependencies, return values, state changes, capabilities, and checked failures. It follows each local branch, loop, match, recovery path, and cleanup block. It includes private helpers and same-file tests. For endpoints, it describes routes, wire inputs, policies, middleware ordering, and configured HTTP behavior.
+
+For example, this complete program uses two source files:
+
+```aug project=spec-guide file=main.aug
+import total from prices
+print(value=total(price=7, quantity=3))
+```
+
+```aug project=spec-guide file=prices.aug
+total(int price, int quantity) returns int:
+    if quantity > 0:
+        return price * quantity
+    return 0
+```
+
+Without any comments, the generated spec lists `total` near the top of the file, explains its two labeled inputs and `int` result, and then describes its behavior:
+
+> - If `quantity` is greater than `0`:
+>   - Return `price` times `quantity`.
+> - Return `0`.
+
+The generated document preserves the actual branch structure and links to the full explanation of each used dependency. Javadoc, when present, appears after the generated behavior as **Author documentation**. It can explain intent that a compiler cannot infer, but readers do not need comments to follow the checked inputs, operations, and outcomes.
+
+Optional contracts use `optional Type`. Specs describe two possible states: a value or null. Omitted inputs become null, so missing and explicit null follow the same branch. If an older program handles missing and null differently, combine those cases deliberately before using the syntax migration command.
+
+## Dependencies stay small and navigable
+
+Each file starts with a short map of its declarations and startup steps, then explains local behavior. A compact dependency section follows it. Each used operation shows its inputs, result, injected values, changes, capabilities, and failures, with a link to the complete explanation. Dependency implementation bodies belong in their own documents.
+
+`import everything` stays valid. The spec lists the names and operations actually used by the file. Adding an unused export does not expand that list. VS Code hover still shows all names available from the import.
+
+The compiler creates offline dependency documents from the installed source versions. Package paths include the package name and exact version; standard-library paths include the compiler version. Documents use relative links and include source links. Commit generated specs and `.aug-spec/` together when you want readers to follow those links without installing dependencies.
+
+## Optional comments, checked when required
+
+Javadoc is optional by default and is included when present. To require it:
+
+```yaml
+spec:
+  require_comments: public
+```
+
+| Value | Requirement |
+| --- | --- |
+| `none` | Default. Include existing Javadoc. |
+| `public` | Require Javadoc for public declarations and methods in this project. |
+| `all` | Also require it for private declarations and methods. |
+
+Implementation methods can inherit documentation from their interfaces. This setting governs your project; it does not require you to edit installed dependencies. Existing validation of `@param`, `@return`, and `@throws` tags still applies.
+
+## Editor and package workflow
+
+In VS Code, use **AugScript: Open Compiled Specification** to generate and preview the current file's document. Save sources first. **AugScript: Generate Specifications** generates the project's documents. Language diagnostics and migration actions use the same compiler as the CLI.
+
+`aug pack` includes adjacent specs and their offline dependency documents in the archive. Consumers import August declarations normally; Markdown files do not change the package's public exports or execute code. See [packages](packages.md).
+
+## Determinism and limits
+
+Generation is offline and deterministic for the same checked sources, configuration, installed dependency versions, and compiler version. It adds no timestamps or machine paths. It uses fixed templates and the compiler's semantic information.
+
+ASD-STE100 guides the wording. The output is best effort Simplified Technical English, without a claim of formal compliance. Native C boundaries are explained through their declared contracts and author documentation; the compiler does not infer a foreign implementation's internals. Shared numeric, ownership, and task rules link to the language reference.
+
+The writer refuses to replace a handwritten neighboring `.aug.md` file. Rename that file before generation. Files marked as generated belong to the compiler; edit their August source or Javadoc and regenerate.