@greenpandastudios/aug-cli 0.19.0

package/docs/language-design-audit.md

@@ -0,0 +1,147 @@
+# AugScript: simplicity and developer scalability
+
+## Readability audit, September 29, 2026
+
+August 0.19 uses ASD-STE100 as guidance for plain technical explanations. The language keeps local behavior and neighboring contracts in view. The deterministic [spec compiler](specifications.md) extends that context to readers who do not read code.
+
+| Finding | Change |
+| --- | --- |
+| Symbolic booleans required translation into prose. | Only `and`, `or`, and `not` are accepted. Comparisons bind before `not`. |
+| Constructor `=>` work interrupted the class header. | `initialize` sits inside the class or record beside its fields and behavior. |
+| Optional values had several spellings and separate missing/null states. | Only `optional Type` is accepted. Its value is T or null; omission becomes null. |
+| Several DI spellings described the same operation. | Use `implement … with …` and `resolve … to …`. Migration actions convert old spellings. |
+| Wildcard imports could obscure the actual dependency surface. | Preserve the requested import syntax; specs explain only names and operations used, with links to complete dependency explanations. |
+| A reader had to assemble branches, private helpers, errors, and tests by hand. | Each `.aug.md` describes all local behavior, with precise-version offline dependency docs. |
+| Required comments could repeat visible code and add ceremony. | Comments remain optional and are pulled into specs. Projects can require public or all declaration/method comments in `main.yaml`. |
+| Effect clauses repeated interface contracts in implementations. | The existing inference for implementations/private helpers remains checked and appears in specs and hover. Public contracts remain explicit. |
+
+Ordinary assignments retain both `=` and `to`. Labeled calls, explicit imports, folder exports, checked failures, mutable access, and scoped sharing retain their existing meaning. These constructs communicate context needed to understand a module; brevity must preserve that context.
+
+The historical audit below records the earlier findings and their evolution.
+
+Audit of the 0.14 compiler, runtime, module system, guide, and VS Code extension on September 28, 2026. The user approved all recommended solutions and optional indentation blocks. Version 0.15 implements that scope; see [the delivery map](implementation-map.md) for accepted spelling, modules, verification, and limits.
+
+The findings below describe the historical 0.14 baseline. Source links now point to the evolved implementation; the current guide and delivery map are authoritative for accepted behavior.
+
+## Why this language exists
+
+AugScript should let a developer, including one working with an LLM, understand a module from the code in front of them. Its interface should communicate inputs, results, dependencies, failures, mutation, and execution order. A change should stay local to the module that owns the behavior.
+
+The two tenets are **simplicity** and **developer scalability**. Concrete design rules follow:
+
+1. Prefer a familiar, canonical spelling for each operation.
+2. Put dependencies and observable effects in the interface.
+3. Make ordinary data easy to create and read.
+4. Make sharing, mutation, and lifetime decisions visible.
+5. Keep a module’s public interface smaller than its implementation.
+6. Enforce module rules in the compiler, rather than relying on everyone remembering conventions.
+7. Keep contracts, documentation, and tests beside the code they explain.
+8. Give developers tools to gather the exact context needed for a change.
+
+These are design goals. Some require changes to earlier decisions, especially shared process bindings, public fields, and mutation through methods. A short natural-language spelling does not, by itself, make its behavior explicit.
+
+## Changes implemented in 0.14
+
+| Previous gap | Change |
+| --- | --- |
+| Creating common data required constructor calls and explicit generic arguments. | List, tuple, set, and map literals infer types; typed declarations and concrete call/return contracts supply empty-literal types. |
+| Lists and maps existed, but sets and tuples did not. | Added hash sets and immutable tuple positions, with typed read operations. |
+| Map lookup scanned every entry. | Map and Set now use hash tables; tuple keys have value equality and hashing. |
+| Statement punctuation was mandatory. | Newlines terminate statements; semicolons remain optional separators. Continuation rules avoid silently joining separate calls. |
+| Error contracts used `throws`. | Contracts read `returns T unless Error`; `throw` remains the failure statement. The editor migrates old contracts. |
+| Several imports required repeated statements. | `import A and B from module` and `import everything from module` are supported. |
+| Sibling imports could accidentally expose a sibling’s imports depending on processing order. | Import resolution uses that file’s own declarations. Neither named nor wildcard imports expose transitive imports. |
+| Wildcard imports hide their actual imported names. | Hover now lists resolved names and source files. Explicit named imports remain the clearest choice. |
+| Behavior examples and regression tests lived outside the language. | Same-file `test / when / it / assert`, CLI discovery/filtering, and an editor test provider. |
+| Test fixtures could otherwise share the production composition root. | Each case gets fresh setup and bindings in a separate native process. Production startup is omitted. |
+| A caught assertion or an empty test could appear successful. | Assertion failure remains a failed case; executing no assertions fails a case. Tests have bounded native execution. |
+| Mutable collections could widen their element types through an alias. | List, Set, and Map type arguments are invariant. |
+| An interface implementation could change parameter ownership silently. | Parameter ownership is checked as part of the interface signature. |
+| A non-void body could fall through and return runtime null. | The compiler requires a value or failure on every path. |
+
+The runnable example is [developer-workflow](../examples/developer-workflow/main.aug); tests are beside [Calculator](../examples/developer-workflow/calculator.aug). See [the language guide](reference.md) and [testing guide](testing.md).
+
+## Baseline findings: dependencies and side effects
+
+| Finding | Evidence at the time of the audit | Recommended solution |
+| --- | --- | --- |
+| **1. A plain method call can mutate shared state.** A caller reading `worker.work()` cannot tell whether it changes the worker, its injected objects, or external state. | Methods carry parameters, results, ownership, and checked errors, but no effect contract in [the AST](../src/ast.ts). Field writes need a local borrow; ordinary calls do not require the caller to know the method’s mutation. | Make functions and methods pure by default. A mutating method declares `changes self`; external effects come from named capabilities and appear in its checked contract. Require the corresponding mutable access at the call site. |
+| **2. Process-wide DI makes sharing the easiest lifetime.** Every resolve of a key receives the same object, even when a developer expects independent state. | [Binding checking](../src/checker.ts) creates one instance per key; [generated C](../src/codegen.ts) stores all bindings in global roots. | Distinguish stateless shared adapters from stateful instances. Add explicit lifetimes or composition scopes. Require an explicit shared-state choice for mutable bindings. Keep one root in main, with module-level composition helpers for large apps. |
+| **3. Explicit resolve expressions are service-locator access.** A dependency can appear deep in a body, absent from the header. | `checkExpression` permits `resolve` wherever expressions are allowed. Function parameters already support the clearer `resolve Type name` form. | Require dependency parameters outside composition/setup code. Offer a fix that lifts a body resolve into a header dependency. Explicit retrieval remains appropriate in main and test setup. |
+| **4. The startup dependency graph misses body lookups and helper calls.** An order-independent binding can read a not-yet-built dependency through its constructor body. | `checkBindings` follows injected fields and constructor interceptor dependencies, rather than every transitive call or resolve in startup code. | First prohibit body-level resolve during construction. Then derive a checked dependency/effect graph from headers and calls, with a diagnostic showing the full cycle or missing edge. |
+| **5. I/O is ambient.** Any file can call print or file I/O without importing or receiving that dependency. File errors are checked, but the ability to touch the filesystem is not visible in the interface. | Built-ins in [the checker](../src/checker.ts), [editor help](../src/help.ts), and [runtime](../runtime/aug_runtime.c). | Model Console, FileReader, and FileWriter as capabilities passed explicitly or injected. Keep convenient output in main and test tooling. Inject clock, randomness, and network capabilities when those features arrive. |
+| **6. Constructor work can perform arbitrary effects.** Resolving a graph can trigger logging, file writes, or other work before the explicit application statements. | Constructor `=>` blocks and constructor interceptors run during eager binding creation. | Keep construction limited to establishing valid local state. Put startup effects in a named, effect-declared method called visibly from main. Check constructor purity. |
+| **7. Interceptors change behavior beyond the visible body.** They can skip execution, replace inputs/results, and add dependencies/errors. A tag shows that there is a wrapper, but its full contract requires another file. | [Interceptor planning](../src/checker.ts), [layer code generation](../src/codegen.ts), and existing chain/error hover. | Preserve explicit tags and written ordering. Add complete layer dependencies, effects, and short-circuit behavior to callable hover and context output. Make each layer satisfy the same effect and mutation rules as its target. Avoid global or implicit interceptor registration. |
+
+## Baseline findings: data, contracts, and ownership
+
+| Finding | Evidence | Recommended solution |
+| --- | --- | --- |
+| **8. Unprefixed constructor fields are public and writable.** A module can expose all of its storage accidentally and let callers bypass invariants. | Header parameters become fields automatically; `_` controls visibility in [project and member checking](../src/checker.ts). | Preserve the public naming rule, but make public fields read-only by default. Require explicit mutable storage. Expose a method for transitions that maintain invariants. Prefer immutable data at module seams. |
+| **9. Plain managed inputs are not a deep read-only guarantee.** A method can mutate referenced objects or invoke another mutating method through a seemingly ordinary input. | Ownership checks focus on direct variables, fields, and known collection operations. Method contracts do not classify mutation. | Track read versus mutable access through calls and nested storage. A managed parameter grants reading; mutation requires a checked borrow or an explicitly declared capability. |
+| **10. Alias and move checking is incomplete.** Two resolves of the same binding, references retrieved from fields/collections, and aliases created by calls may refer to the same object without a common tracked root. Loops are checked once rather than to a fixed point. | `aliasRoot`, `rootName`, `mergeMoved`, and block checking in [checker.ts](../src/checker.ts). | Build a control-flow analysis that tracks origins, loans, moves, escape, and loop re-entry. Include binding identity and nested references. Until then, treat the ownership implementation as a prototype rather than a proof of exclusive access. |
+| **11. General generic variance is too permissive.** Mutable built-ins are now invariant, but user-defined generic types can still widen arguments through assignability. | `assignable` recursively checks other same-ID generic arguments; classes may have mutable fields and interfaces may consume their type parameter. | Make user-defined generic types invariant by default. Add explicit checked variance only when a type is proven to expose its parameter solely for reading or writing. Add constrained generics with clear diagnostics. |
+| **12. Generic inference and constraints are uneven.** Collection inputs now infer nested generic arguments, but unresolved parameters, multiple competing candidates, and generic DI specialization need stronger checks. | `inferCallType`, `resolveType`, and type-keyed DI in [checker.ts](../src/checker.ts). | Require a concrete inference result at each call; report conflicts at argument labels and show the expected constraint. Use one substitution/unification implementation for functions, classes, interfaces, interceptors, and DI. |
+| **13. Missing values are difficult to use safely.** Map.get returns a nullable result, but a non-null check does not narrow a class reference for a later method call. | Nullable assignment/receiver checks exist; flow narrowing is absent. | Add flow-sensitive narrowing after `if value != null` and early-return guards. Consider an explicit result/option type when absence carries domain meaning. Avoid a unchecked “trust me” conversion. |
+| **14. Some safe-looking operations abort the entire process.** Invalid list positions and division by zero bypass the `unless` model. | `fail()` in [the runtime](../runtime/aug_runtime.c) exits immediately. Tuple constant bounds are checked, but list indexes are dynamic. | Define which failures are recoverable. Use checked IndexError/ArithmeticError or a safe nullable/result operation for dynamic access. Reserve process aborts for invariant corruption and unrecoverable allocation failures. |
+| **15. Broad `unless Error` and print-only catch fixes can hide intent.** An unfamiliar reader loses the failure cases or sees errors silently consumed. | Root Error contracts and the catch-and-print fix in [fixes.ts](../src/fixes.ts). | Prefer specific public error contracts. Offer propagate-with-unless and deliberate recovery fixes before a generic print handler; flag unused caught errors or catch blocks that merely discard failures. Explain which layers add errors. |
+| **16. Mandatory interfaces can add ceremony for simple data.** An empty marker interface exists only to let a data holder be declared. | Every class requires implements; there is no record/value declaration. | Keep explicit interfaces for substitutable behavior. Add a first-class immutable record/value feature for data, with labeled construction, structural equality, and validation where needed. This is a new design decision, not implemented syntax. |
+| **17. Some operations still lack readable data syntax.** Collection creation is concise now, but reading tuples requires `.get(index=...)`, and there are no iteration, destructuring, named records, or pattern matching features. | [Parser](../src/parser.ts) and built-in collection methods. | Add a small, consistent set: labeled record fields, tuple destructuring, `for item in items`, and checked matching. Choose readable constructs that expose types and missing cases. Keep shortcuts out if they obscure data shape. |
+
+## Baseline findings: modules and natural-language consistency
+
+| Finding | Evidence | Recommended solution |
+| --- | --- | --- |
+| **18. Everything imports weaken local dependency lists.** Adding an export elsewhere changes the importing scope, even if the consumer’s text does not change. | The newly supported wildcard import in [project.ts](../src/project.ts). Visibility and collisions are enforced, and hover shows its expansion. | Keep the requested feature. Provide an “expand to named imports” action and an optional production lint. Prefer it in composition roots or small curated modules; use named imports in implementation modules. |
+| **19. Public-by-name still exports a broad sibling surface.** A declaration need not be listed in export.aug to be imported by a sibling file. | The direct sibling path takes public local declarations; export.aug controls only folder crossings. | Preserve the chosen visibility rule, but lint accidental public helpers and broad module surfaces. Encourage `_` for implementation helpers. Offer an optional stronger module policy for large projects. |
+| **20. Private constructor labels expose private spelling.** An external caller must know `_value` to construct a class with that private field. | The documented/tested `Box(_value=2)` behavior in [the guide](reference.md). | Separate the public constructor label from private storage, or make a public parameter initialize a named private field. Keep the distinction explicit in the header and document it in signature help. |
+| **21. Module edges are visible but architecture is not enforced.** Cycles, imports across domain layers, and dependency fan-out can grow into a shared monolith. | Folder exports enforce access, but [project.ts](../src/project.ts) has no import-cycle or allowed-dependency policy. | Check import cycles and let modules declare allowed dependencies. Report changed module edges and interface growth. Use fan-out and mutable sharing as warning signals; avoid arbitrary file-length bans that punish deep, cohesive modules. |
+| **22. Syntax has multiple historical spellings.** Bind/implement, assignment/resolve forms, comma/and errors, and explicit/implicit void increase the amount of grammar an unfamiliar reader must know. | Parser and help contain accepted alternatives; class/function/throws are explicitly rejected. | Establish a formatter’s canonical output: implement/with, resolve/to, optional semicolons omitted, and explicit named imports. Preserve `=` and `to` as requested, but format consistently within a project. Remove legacy bind after a migration period if desired. |
+| **23. Implements decides whether a header is a class.** Removing the keyword simplified declarations, but a missing implements can turn a header into a function and produce a distant error. Brackets also serve lists and annotations. | Speculative declaration lookahead and annotation disambiguation in [parser.ts](../src/parser.ts). | Retain the agreed bare syntax. Improve diagnostics for class-shaped headers, retain precise declaration symbols in navigation, and publish a small grammar with unambiguous line-boundary rules. Avoid adding more context-dependent header roles. |
+| **24. Tests are close to behavior, but can make files large and cover only classes.** Function modules and large suites need a similarly local workflow without requiring a class wrapper. | The new test grammar and [test runner](../src/testing.ts) support same-file class suites and flat groups. | Add function suites, parameterized cases, reusable explicitly imported fixtures, and coverage. Keep the primary tests beside their declaration. Put large integration tests in a separate module with explicit capabilities. In-memory isolation already exists; external effects need adapters or isolated resources. |
+
+## Baseline findings: developer tools and compiler modules
+
+| Finding | Evidence | Recommended solution |
+| --- | --- | --- |
+| **25. Correct understanding still requires context assembly by hand.** Import and tag navigation helps, but there is no command that returns a module’s complete contract and provenance. | CLI has check, symbols, definition, completion, hover, fixes, and tests; no explain/context command. | Add `aug explain` and `aug context`: exact public contracts, imported names and origins, transitive DI, effects, checked errors, interceptor order, and relevant tests. Include source locations and bounded context selection. Make the output useful both to humans and LLM tooling. |
+| **26. Documentation can drift from code.** Javadoc is displayed, but described parameters/errors, public exports, and guide snippets are not checked against the compiler. | [Javadoc parsing](../src/javadoc.ts) formats comments independently of type checking; snippets are maintained manually. | Validate documentation tags against signatures. Diagnose missing public API docs when a project enables that policy. Compile executable documentation examples and show inferred contracts beside prose. Tests should illustrate behavior and limitations, rather than repeat implementation details. |
+| **27. Built-in contracts are duplicated across modules.** Adding Set required edits in the checker, runtime emitter, help, completion, and grammar. This increases the context required for a small change. | Built-in dispatch in [checker.ts](../src/checker.ts), [codegen.ts](../src/codegen.ts), [editor.ts](../src/editor.ts), [help.ts](../src/help.ts), and the grammar. | Create a deep built-in module: one declarative contract registry for labels, types, mutability, errors, and documentation; checker and editor consume it. Keep C runtime adapters behind a narrow seam and verify behavior through native programs. |
+| **28. The checker owns many unrelated policies.** Type resolution, interface merging, DI ordering, ownership, errors, and interception share one large implementation. The editor also reconstructs scope from syntax. | [checker.ts](../src/checker.ts) and [editor.ts](../src/editor.ts). | Expose a resolved semantic model with symbols, scopes, callable contracts, and provenance. Move DI, ownership/effects, and interceptor lowering into modules with small interfaces and shared type operations. Test through their interfaces. A file split without reducing caller knowledge would not improve depth. |
+| **29. Every editor request reloads and checks a whole project.** Main requires all production composition to be valid even when a developer is editing an isolated module. | CLI reloads the project; the extension starts a compiler process for each request. Test analysis is also repeated per case. | Add an incremental language server and cached module checking. Separate type-contract validation from composition completeness; keep whole-application DI validation as a build gate. Let developers get meaningful local diagnostics while the composition root is unfinished. |
+| **30. The build/runtime contract is narrower than its surface suggests.** Native C output still uses tagged values and dynamic member lookup. int is wider in the runtime than the C FFI mapping; strings/file I/O have NUL and encoding limitations; configuration is a small YAML subset checked during build. | [Code generation](../src/codegen.ts), [runtime](../runtime/aug_runtime.c), and [CLI configuration](../src/cli.ts). | Specify numeric range/overflow, text encoding, FFI widths, and ABI conversions. Validate configuration during check and surface native diagnostics at AugScript locations. Benchmark real workloads before promising speed. Add source maps/debugger support and reproducible package/module versions as the project grows. |
+
+## Approved implementation sequence
+
+### First: make the contracts trustworthy
+
+Complete generic invariance/inference and control-flow ownership checks. Define runtime failure behavior. These are compiler correctness tasks; their spelling should not become a user configuration option.
+
+### Second: make effects and sharing visible
+
+Adopt pure defaults, read-only public data, declared mutation, explicit capabilities, and header-only DI outside composition code. Extend the same rules through interfaces and interceptors. This directly addresses the biggest current conflict with the tenets: shared state can change behind an innocent-looking call.
+
+Historical proposal — **now accepted and implemented in 0.15**, with the canonical clause order documented in the reference:
+
+```text
+calculate(int price, int quantity) returns int
+
+Counter() implements ICounter {
+    increment() changes self
+}
+
+save(resolve FileWriter files, string path, string content)
+    uses files.write unless FileError
+```
+
+The cost is additional contract text for effectful operations and more compiler analysis. The benefit is that the caller can see and check the behavior without reading every helper body. Effects should name the actual dependency or state being changed; a generic `impure` escape hatch would reveal too little.
+
+### Third: make context and modules easy to navigate
+
+The semantic model, explain/context commands, canonical formatting, wildcard expansion, module dependency checks, validated docs, incremental editor, immutable records, and function suites are delivered. Record and function-test semantics are defined in the current guide.
+
+## What should stay
+
+Keep explicit imports, export.aug folder boundaries, labeled arguments, same-file tests, checked failure contracts, explicit interceptor tags, and main as the composition root. Keep ordinary reads easy. Keep classes free from class inheritance and interfaces as explicit behavior contracts.
+
+The goal is a module with a small interface that states everything its caller needs to know, substantial behavior behind it, and changes with good locality. Enforce effects, sharing, and dependencies to make that possible; formatting alone cannot prevent a monolith.

package/docs/maintaining-docs.md

@@ -0,0 +1,43 @@
+# Keeping documentation current
+
+Documentation is part of a language change. The canonical wiki is this repository's `docs` directory, reviewed and versioned with the compiler. GitHub Pages renders these same files; an independently edited GitHub Wiki would create a second source of truth.
+
+## Where to make a change
+
+| Change | Update in the same commit |
+| --- | --- |
+| Syntax, type/effect/ownership/DI rules | `docs/reference.md`, relevant grammar/testing/web guide and `src/help.ts` |
+| Public library signature or behavior | Javadoc beside its declaration in `src/stdlib`, the relevant guide and gap ledger |
+| Diagnostic or editor behavior | `src/help.ts`, diagnostics/tooling guide and VS Code changelog |
+| CLI, packages, configuration or supported platform | Tooling/packages/releasing guide and package metadata |
+| Completed or deferred feature | Implementation map, gap ledger and changelog |
+
+Public comments should explain observable behavior, named inputs, errors, side effects, and limits. Keep dependencies explicit in examples. Record incomplete capabilities in the gap ledger; do not imply that an unimplemented proposal is usable.
+
+## Generated reference
+
+```sh
+npm run docs:generate
+npm run docs:check
+npm run docs:build
+```
+
+The API generator reads each `export.aug`, resolves the actual public declaration, and uses the same Javadoc/inherited documentation path as hover. It includes public methods and excludes private native helpers. The language constructs page comes from editor help and collection operation contracts. Commit generated Markdown so GitHub readers and package users can read it without building a site. CI rejects stale generated pages.
+
+The generator also runs the deterministic spec compiler for every standard-library source file. Commit these adjacent `src/stdlib/**/*.aug.md` files. Unlike public API pages, full source specs include private helpers and all local behavior. For application or third-party package source changes, run `aug spec PROJECT` and verify `aug spec PROJECT --check`. See [the user workflow](specifications.md).
+
+## Repository example gallery
+
+`docs/example-projects.json` lists the complete projects shown in [the example gallery](examples/index.md), including the measured benchmark programs. `docs:generate` checks each application and its same-file tests, formats each file in indentation and braces styles, and runs the spec compiler. It publishes code and specs side by side under `docs/examples`, with dependency links that stay in the wiki. Long code lines wrap visually without changing copied source. It also refreshes adjacent example specs and their offline dependency copies. Generation uses temporary project copies; the package-consumer example installs its local dependency offline there. It does not edit example source or create package locks in the checkout.
+
+Keep titles and descriptions in the catalog current when adding or changing an example. `docs:check` rejects source/spec drift. Gallery tests require every repository example and benchmark source to be represented, check both displayed syntax styles, and follow the wiki's generated links and declaration anchors. Readers can switch code style with a mouse or keyboard; their choice is kept between pages on the same browser.
+
+## Executable examples
+
+Each runnable `aug` fence declares `project=NAME file=PATH`. A guide may spread one project across several fences. Add expected output/test counts to `docs/examples.json`. The documentation test assembles, checks, runs or builds, tests, formats, and checks those projects again. API signatures use `text` fences because a declaration header is not a complete application.
+
+```sh
+node --test tests/documentation.test.mjs
+```
+
+CI checks documentation on every push and pull request. Pull requests changing language/runtime/library/tooling behavior must update a handwritten guide or changelog; the policy check enforces that requirement. The Pages deployment publishes only the documented branch version, with search and source links. Use tags and GitHub history to read earlier releases.

package/docs/packages.md

@@ -0,0 +1,184 @@
+# Packages and installation
+
+The [augscript monorepo](https://github.com/GreenPandaStudios/augscript) versions the compiler, libraries, documentation, and editor together. Release packages contain the files needed to use them; they do not run install scripts or silently build native libraries.
+
+| Distribution | Package | Provides |
+| --- | --- | --- |
+| CLI | `@greenpandastudios/aug-cli` | `aug`, `aug-cli`, `aug-native`, compiler, language server, C runtime, guides and examples |
+| Standard library | `@greenpandastudios/aug-stdlib` | `august.io`, `august.json`, `august.time`, `august.memory` |
+| Web library | `@greenpandastudios/aug-web` | `august.web`, HTTP capabilities and helpers |
+| Crypto library | `@greenpandastudios/aug-crypto` | `august.crypto`, cryptographic capability, RSA JWK and signed JWT helpers |
+| VS Code | `augscript.augscript` / `.vsix` | Syntax, file icons, hover, completion, fixes, navigation, tests and bundled compiler |
+
+## From a checkout
+
+Requires Node.js 24+, npm, and a C11 compiler. Full web/crypto native builds run on macOS and Linux; the repository's Docker recipes supply the Linux build tools and libraries. Other platforms remain outside the tested support matrix.
+
+```sh
+git clone git@github.com:GreenPandaStudios/augscript.git
+cd augscript
+npm ci
+node scripts/bootstrap-native.mjs --extract-only --only minicoro,yyjson
+node bin/aug.mjs run examples/approved-design
+node scripts/bootstrap-native.mjs
+node bin/aug.mjs run examples/oidc-login
+```
+
+## Install release tarballs
+
+Until registry publication is configured, download all four `.tgz` files from the same [GitHub release](https://github.com/GreenPandaStudios/augscript/releases). Install them together, replacing VERSION with the release version:
+
+```sh
+npm install --global ./greenpandastudios-aug-stdlib-VERSION.tgz ./greenpandastudios-aug-web-VERSION.tgz ./greenpandastudios-aug-crypto-VERSION.tgz ./greenpandastudios-aug-cli-VERSION.tgz
+aug --version
+aug --help
+aug-native
+aug check path/to/project
+aug run path/to/project
+```
+
+The CLI depends on exact matching library versions. Import spellings stay `import Crypto from august.crypto`; npm package names never enter August source. The packaged CLI loads the separate installed libraries, and editor navigation opens their real `.aug` files.
+
+Native dependencies use `~/.cache/augscript/native/VERSION/PLATFORM-ARCH` for an installed CLI. Source checkouts use `.aug-native`. `AUG_NATIVE_HOME` selects a shared cache for CLI and VS Code; building dependencies is an explicit command.
+
+For core programs and JSON without web/crypto, `aug-native --extract-only --only minicoro,yyjson` downloads just the portable C sources. Compiler checkpoints use minicoro even in ordinary programs; this source dependency must be present before native execution. Full web/crypto bootstrap is available on macOS and Linux.
+
+## npm registry
+
+Create a project with the published CLI:
+
+```sh
+npx @greenpandastudios/aug-cli@next init hello-august
+```
+
+`aug init DIRECTORY` creates a checked application with `main.aug`, a public interface and implementation, a same-file test, README, and `.gitignore`. It refuses a nonempty directory. The npm package exposes `aug-cli` as a binary so `npx` can select the executable by package name. The CLI brings its three matching libraries. Early releases use the `next` dist tag. **This npm package has not been published yet**, so use the checkout or release tarballs above until the owner configures npm access. Registry and Marketplace publication require their own owner accounts; a GitHub account does not grant those identities. See [releasing](releasing.md) for configuration and [getting started](getting-started.md) for the starter command.
+
+## VS Code
+
+Install **AugScript** (`augscript.augscript`) from the VS Code Extensions view once its [Marketplace listing](https://marketplace.visualstudio.com/items?itemName=augscript.augscript) is published. The listing is currently unpublished pending owner identity setup. Release publication runs the Marketplace workflow described in [releasing](releasing.md).
+
+For direct installation, download the matching `.vsix` from [GitHub Releases](https://github.com/GreenPandaStudios/augscript/releases) and choose **Extensions → Install from VSIX**.
+
+The extension bundles the same compiler sources, standard declarations, native bootstrap, guides, and examples. Set `augscript.nativeHome` to an existing dependency build directory. Node.js 24+ remains required.
+
+## Package model
+
+`packages/*/package.json` and `aug-package.json` are release manifests. Canonical code lives in `src`, `runtime`, and `src/stdlib`; generated staging directories live under ignored `dist`. `npm run package:packages` builds JavaScript and real npm tarballs. `npm run test:packages` installs those tarballs outside the checkout and checks imports, navigation, native execution, and compatibility.
+
+User packages ship August source, retain their own public boundaries, and compile into the application's native executable. They use npm for archive/registry transport and August for visibility, compatibility, dependency scopes and checking. Changing builtin libraries independently of the compiler is unsupported; general native adapter ABI/version distribution remains future work.
+
+With the full native bootstrap ready, `npm run test:packages -- --native` additionally builds the OIDC example and runs its signed-identity tests using the installed CLI and separate packages.
+
+## Author a package
+
+Create a standalone library; it needs no `main.aug`:
+
+```sh
+aug package init my-math --name @your-npm-name/aug-math
+aug check my-math
+aug test my-math
+aug package pack my-math
+```
+
+The scaffold includes `src/arithmetic.aug` with a same-file test, `src/export.aug`, `aug-package.json`, and npm's `package.json`. Public API, Javadoc and tests stay beside the implementation:
+
+```text
+// src/arithmetic.aug
+/** Add two integers. @param left First integer. @param right Second integer. */
+add(int left, int right) returns int:
+    return left + right
+
+test add:
+    when addition:
+        it adds:
+            assert(add(left=2, right=3) == 5)
+
+// src/export.aug
+export add from arithmetic
+```
+
+`aug-package.json` owns August metadata and dependency aliases:
+
+```json
+{
+  "format": 1,
+  "name": "@your-npm-name/aug-math",
+  "version": "0.1.0",
+  "compiler": "0.19.0",
+  "source": "src",
+  "dependencies": {}
+}
+```
+
+`package.json` supplies npm transport metadata, description, license, README and the files to include. `aug install` and `aug package pack` synchronize its name, version and dependencies from the August manifest. Keep the source folder and `aug-package.json` in its `files` list. Pack checks every declaration and test closure before creating `.aug-build/packages/your-npm-name-aug-math-0.1.0.tgz`. It checks test code; execute the cases with `aug test` before release.
+
+After authenticating with an npm account that owns the namespace, publish that verified archive:
+
+```sh
+npm publish my-math/.aug-build/packages/your-npm-name-aug-math-0.1.0.tgz --access public
+```
+
+This is an explicit author action; `aug install` never publishes or executes dependency lifecycle scripts. August does not require a new registry account in addition to npm. See [npm's package publishing guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/).
+
+## Use a package
+
+In the consuming application's `main.yaml`, choose a readable import alias:
+
+```yaml
+packages:
+  math: "npm:@your-npm-name/aug-math@0.1.0"
+```
+
+Install explicitly, then import the public name:
+
+```sh
+aug install my-app
+aug run my-app
+```
+
+```text
+// my-app/main.aug
+import add from math
+print(value=add(left=20, right=22))
+```
+
+Local development uses the same source syntax. Replace the specification with `"../my-math"`, `"file:../my-math"`, or a path to the `.tgz`. `aug install` snapshots a local directory, so reinstall after editing its source. Check and build never fetch dependencies or silently refresh a local package. There are no symlinked live dependencies.
+
+Only the source root's `export.aug` is visible to another package. To expose a submodule, write `export folder parsing` there and provide `src/parsing/export.aug`; consumers can then use `import Parser from math.parsing`. Private `_names`, files and folders remain inaccessible. `import everything` follows the same public surface. An alias cannot shadow a local file/folder or use the reserved `august` name.
+
+Module dependency policies use the alias path (`math` or `math/parsing`) for external edges. Consumer architecture/style lints apply to its own source; they do not impose its conventions on library internals.
+
+Ctrl-click an imported declaration, `from`, or a path segment to open the installed source or its export file. Hover preserves its Javadoc. VS Code recognizes a standalone library from `aug-package.json` and refreshes when the manifest or lock changes.
+
+## Dependencies between libraries
+
+Declare dependencies in the library's August manifest instead of `main.yaml`:
+
+```json
+"dependencies": {
+  "math": "npm:@your-npm-name/aug-math@0.1.0"
+}
+```
+
+Run `aug install` inside that library and use `import add from math`. Each package sees its own declared aliases. A consuming app cannot import a transitive alias unless it also declares that dependency. Multiple package versions have distinct type identities; duplicate copies of the same version share declarations only when their source and dependencies agree. Changed code with the same package name/version is rejected when conflicting copies would coexist.
+
+Registry dependencies require exact versions. Ranges, latest tags, Git dependencies and arbitrary URLs are unsupported. Local paths are useful within a development workspace; publish registry references for libraries other developers will install.
+
+## Reproducible builds
+
+Commit `aug.lock.json` with your project. It records specifications, the installed graph, exact names/versions, npm integrity metadata, the compiler version, and hashes of source/manifests. `.aug-packages` is an ignored installed snapshot.
+
+```sh
+aug install my-app --frozen
+aug check my-app
+aug test my-app
+aug build my-app
+```
+
+`--frozen` requires a matching lock and unchanged source graph. `--offline` additionally prohibits fetching uncached dependencies; a fresh machine may need one online install before it can work offline. Editing the installed source produces a diagnostic requiring a reinstall. The compiler version must match exactly while the language is experimental.
+
+Libraries support `check`, same-file `test`, formatting, explain, editor help, and packing. `run`, `build`, `bench` and server OpenAPI generation belong to an application with `main.aug`. Consumer tests run the consumer's suites; dependency tests are checked and executed by the package author. Arbitrary C source, native build hooks, precompiled August binaries, compiler plugins and stable native ABIs are outside this package format.
+
+`aug spec` also works on source libraries. `aug pack DIRECTORY` is an alias for `aug package pack DIRECTORY`. Packing refreshes and includes adjacent `.aug.md` files and `.aug-spec/` so the package carries complete source explanations and precise-version offline dependency links. See [compiled specifications](specifications.md).
+
+The [package example](../examples/packages/README.md) exercises the author and consumer workflow locally. The installer uses [npm aliases](https://docs.npmjs.com/cli/v11/using-npm/package-spec/) and [npm install](https://docs.npmjs.com/cli/v11/commands/npm-install/) with lifecycle scripts disabled and local packages installed as copied archives.