Add package workspace guide

.llm/BETA_5_PACKAGE_WORKSPACE_DISCIPLINE.md

@@ -23,6 +23,8 @@ ABI promise.
 - Add workspace package and dependency summaries to `glagol doc`.
 - Teach generated workspace templates and canonical workspace examples to
   declare `default_package = "app"`.
+- Add `docs/language/PACKAGES.md` as the public beta local package/workspace
+  guide, including the no-registry/no-lockfile policy.
 - Keep dependency resolution local-path-only and deterministic.
 
 ## Acceptance Gates

README.md

@@ -165,6 +165,7 @@ solving, package publishing, and stable package ABI/layout remain deferred.
 
 - [Language Manifest](docs/language/MANIFEST.md)
 - [Language Specification](docs/language/SPEC-v1.md)
+- [Local Package And Workspace Guide](docs/language/PACKAGES.md)
 - [Standard Library API Catalog](docs/language/STDLIB_API.md)
 - [Compiler Manifest](docs/compiler/GLAGOL_COMPILER_MANIFEST.md)
 - [Post-Beta Roadmap](docs/POST_BETA_ROADMAP.md)

docs/POST_BETA_ROADMAP.md

@@ -135,9 +135,10 @@ In progress after `1.0.0-beta.4`: local workspaces can declare
 `default_package` to select the build/run entry package when multiple packages
 have entry modules. Duplicate normalized member paths and missing default
 package references are dedicated diagnostics. Workspace documentation now
-includes package and local dependency summaries. Lockfiles, remote registries,
-semver solving, publishing, optional/dev/target dependencies, and stable
-package ABI/layout remain out of scope.
+includes package and local dependency summaries, and
+`docs/language/PACKAGES.md` records the beta local-package rules. Lockfiles,
+remote registries, semver solving, publishing, optional/dev/target
+dependencies, and stable package ABI/layout remain out of scope.
 
 Why fifth: stable package rules are a prerequisite for a usable public language,
 but remote publishing can wait.

docs/README.md

@@ -2,8 +2,8 @@
 
 This directory contains the public documentation for Slovo and Glagol.
 
-- `language/`: language manifest, specs, roadmap, release notes, and historical
-  language examples
+- `language/`: language manifest, specs, local package guide, roadmap, release
+  notes, and historical language examples
 - `compiler/`: Glagol compiler manifest, roadmap, contribution notes, and
   release notes
 - `papers/`: technical whitepapers and generated PDF publications

docs/compiler/RELEASE_NOTES.md

@@ -22,6 +22,8 @@ integration/readiness release, not the first real beta.
   summary with members, packages, and local package dependency edges.
 - `glagol new --template workspace` and the canonical local workspace examples
   now declare `default_package = "app"`.
+- `docs/language/PACKAGES.md` now documents the beta local workspace/package
+  rules and the explicit no-registry/no-lockfile policy.
 
 ## 1.0.0-beta.4
 

docs/compiler/ROADMAP.md

@@ -34,7 +34,8 @@ Current unreleased work is the package/workspace discipline slice. It adds
 `[workspace] default_package = "name"` for deterministic build/run entry
 selection in multi-entry workspaces and tightens workspace-member/default
 package diagnostics. Workspace docs now include package/dependency summaries.
-Registries, lockfiles, semver solving, and publishing remain deferred.
+`docs/language/PACKAGES.md` records the beta local-package rules. Registries,
+lockfiles, semver solving, and publishing remain deferred.
 
 The final experimental precursor scope is `exp-125`. Its unsigned direct-value
 flow, parse/format runtime lanes, and matching staged stdlib helper breadth

docs/language/PACKAGES.md

@@ -0,0 +1,120 @@
+# Slovo Local Package And Workspace Guide
+
+Sanjin Gumbarevic<br>
+hermeticum_lab@protonmail.com
+
+This guide documents the current beta local package model. It is intentionally
+smaller than a package manager: Slovo supports closed local workspaces,
+package metadata, local path dependencies, package-qualified imports, and
+deterministic project-wide tooling.
+
+Remote registries, lockfiles, semantic-version solving, package publishing,
+optional/dev/target dependencies, feature flags, build scripts, package
+archives, and stable package ABI/layout promises are not part of the current
+beta contract.
+
+## Workspace Manifest
+
+A workspace root contains `slovo.toml` with a `[workspace]` section:
+
+```toml
+[workspace]
+members = ["packages/app", "packages/mathlib"]
+default_package = "app"
+```
+
+`members` is required and must be a non-empty array of relative paths that stay
+under the workspace root. Paths are normalized before package loading, so
+spelling the same member twice is invalid.
+
+`default_package` is optional. When more than one package has its configured
+entry module, `glagol build` and `glagol run` use `default_package` to select
+the entry package. Without it, build/run require exactly one package with an
+entry module.
+
+## Package Manifest
+
+Each member contains its own `slovo.toml`:
+
+```toml
+[package]
+name = "app"
+version = "0.1.0"
+source_root = "src"
+entry = "main"
+
+[dependencies]
+mathlib = { path = "../mathlib" }
+```
+
+`name` must be lowercase ASCII and may contain digits or `-` after the first
+letter. `version` currently uses literal `MAJOR.MINOR.PATCH` numeric shape.
+The version is metadata for manifests and generated documentation; it is not
+used for solving dependency constraints.
+
+`source_root` defaults to `src`. `entry` defaults to `main`. Source roots and
+dependency paths must stay inside the workspace/package boundary after
+normalization and canonical path checks.
+
+Dependencies are local path records only. The dependency key must match the
+target package name:
+
+```toml
+mathlib = { path = "../mathlib" }
+```
+
+## Imports
+
+Within a workspace, a package imports a dependency module through the package
+name and module name:
+
+```slo
+(module main)
+
+(import mathlib.math (add_one))
+
+(fn main () -> i32
+  (add_one 41))
+```
+
+Only exported declarations are visible across package boundaries. Packages do
+not imply automatic imports, glob imports, aliases, re-exports, or registry
+resolution.
+
+## Tooling
+
+The project-wide commands operate over the closed workspace graph:
+
+```bash
+glagol check path/to/workspace
+glagol test path/to/workspace
+glagol fmt --check path/to/workspace
+glagol fmt --write path/to/workspace
+glagol doc path/to/workspace -o docs-out
+glagol build path/to/workspace -o app-bin
+glagol run path/to/workspace
+glagol clean path/to/workspace
+```
+
+`glagol doc <workspace>` emits a deterministic workspace summary with members,
+packages, and local package dependency edges before the module sections.
+
+## Diagnostics
+
+The package/workspace gate covers these user-facing error families:
+
+- missing member manifests
+- duplicate normalized workspace members
+- invalid member or dependency paths
+- invalid package names and versions
+- duplicate package names
+- missing local path dependencies
+- dependency key/name mismatches
+- package dependency cycles
+- private cross-package imports
+- ambiguous workspace build/run entry packages
+- missing or invalid `default_package` references
+- selected default packages that lack their configured entry module
+
+These diagnostics are part of the beta package discipline surface, but the
+exact text remains subject to beta refinement before stable `1.0.0`.

docs/language/RELEASE_NOTES.md

@@ -30,6 +30,8 @@ diagnostics bundle.
   deterministic summary of members, packages, and local dependency edges.
 - Generated workspace templates and the canonical local workspace examples now
   declare `default_package = "app"`.
+- `docs/language/PACKAGES.md` now documents the beta local package/workspace
+  rules and the explicit no-registry/no-lockfile policy.
 
 ## 1.0.0-beta.4
 

docs/language/ROADMAP.md

@@ -21,7 +21,8 @@ Current unreleased work is the package/workspace discipline slice. It adds
 `[workspace] default_package = "name"` for deterministic build/run entry
 selection in multi-entry workspaces and tightens duplicate-member/default
 package diagnostics. Workspace docs now include package/dependency summaries.
-Registries, lockfiles, semver solving, and publishing remain deferred.
+`docs/language/PACKAGES.md` records the beta local-package rules. Registries,
+lockfiles, semver solving, and publishing remain deferred.
 
 The final experimental precursor scope is `exp-125`, defined in
 `.llm/EXP_125_UNSIGNED_U32_U64_NUMERIC_AND_STDLIB_BREADTH_ALPHA.md`. Its