doc: update with workspace and other 0.16 changes

docs/configuration.md

@@ -138,6 +138,51 @@ default. Set to `"http"` for local test registries.
 protocol = "https"
 ```
 
+### `registry.<name>.oci.accept_invalid_certificates`
+
+- Type: bool, default `false`
+
+Skip TLS certificate validation. For local self-signed test registries only.
+
+### `registry.<name>.oci.extra_root_certificates`
+
+- Type: list of inline-tables `{ encoding = "pem" | "der", data = "<cert>" }`
+- Default: `[]`
+
+Additional root certificates trusted for TLS. `data` holds the certificate
+bytes as a string; use TOML multi-line literals for PEM blocks. Useful when a
+private OCI registry is fronted by an internal CA.
+
+```toml
+[[registry."internal.example.com".oci.extra_root_certificates]]
+encoding = "pem"
+data = """
+-----BEGIN CERTIFICATE-----
+MIIB...
+-----END CERTIFICATE-----
+"""
+```
+
+### Environment variable authentication
+
+For OCI registries, an environment variable of the form
+`WKG_REGISTRY_<REGISTRY>_AUTH_<SCHEME>` overrides any credentials configured
+under `[registry."<name>".oci.auth]`. `<REGISTRY>` is the registry name with
+every non-ASCII-alphanumeric character replaced by `_` and upper-cased.
+`<SCHEME>` is the auth scheme.
+
+| Registry         | Envvar                                    |
+| ---------------- | ----------------------------------------- |
+| `example.com`    | `WKG_REGISTRY_EXAMPLE_COM_AUTH_BEARER`    |
+| `localhost:8008` | `WKG_REGISTRY_LOCALHOST_8008_AUTH_BEARER` |
+| `foo.bar/baz` | `WKG_REGISTRY_FOO_BAR_BAZ_AUTH_BEARER` |
+
+NOTE: only `BEARER` scheme is currently supported through environmental variables.
+
+Useful for registries that expect a bearer token rather than a
+username/password pair, and for supplying credentials in CI without writing
+them to a config file.
+
 ### `registry.<name>.local.root`
 
 - Type: string (filesystem path)

docs/manifest.md

@@ -9,20 +9,36 @@ and *is entirely optional*. Projects are not required to use this file.
 Currently it serves two purposes: adding additional metadata and overriding
 versions/dependencies.
 
+*NOTE*: A top-level `[workspace]` table is mutually exclusive with top-level
+`[overrides]` and `[metadata]`: a workspace root uses `[workspace.metadata]`
+instead, and members manifests have their own `[overrides]` / `[metadata]`.
+
 ### Format
 
+Single-package layout:
+
 ```toml
 [overrides]
 "my:local-dep" = { path = "../local-dep/wit" }
 
 [metadata]
-authors = ["WasmPkg <wasm-pkg@bytecodealliance.org>"]
-categories = ["wasm-pkg"]
+authors = "WasmPkg <wasm-pkg@bytecodealliance.org>"
 description = "WASI HTTP interface"
 license = "Apache-2.0"
-documentation = "https://docs.foobar.baz"
 homepage = "https://foobar.baz"
 repository = "https://github.com/bytecodealliance/wasm-pkg-tools"
+revision = "f00ba4"
+```
+
+Workspace root layout:
+
+```toml
+[workspace]
+members = ["pkg-a", "pkg-b/wit", "examples/*/wit"]
+
+[workspace.metadata]
+authors = "WasmPkg <wasm-pkg@bytecodealliance.org>"
+license = "Apache-2.0"
 ```
 
 ### `overrides`
@@ -38,18 +54,39 @@ developing two components together.
 "my:local-dep" = { path = "../local-dep/wit" }
 ```
 
-### `metadata.authors`
+### `workspace.members`
+
+- Type: list of strings (paths; gitignore-style globs allowed)
 
-- Type: list of strings
+Directories that make up the workspace. Each entry is either a literal path or
+a glob (e.g. `"examples/*/wit"`); globs expand relative to the workspace root
+and skip entries with no `.wit` files. Used by `wkg fetch --workspace` and
+`wkg publish --workspace` to operate on every member in one invocation.
+Members share the workspace-level `wkg/deps` and `wkg/config.toml` next to the
+root manifest.
 
-Author list. Also consumed by downstream language tooling that reads
-`wkg.toml`.
+### `workspace.metadata`
 
-### `metadata.categories`
+- Type: same shape as [`metadata`](#metadataauthors) below
 
-- Type: list of strings
+Workspace-wide package metadata applied to every member. Set here instead of
+top-level `[metadata]` when `[workspace]` is present.
 
-Freeform category tags.
+### Member declarations
+
+- Type: `{ workspace = "path/to/root" }` (optional)
+
+A member `wkg.toml` typically has no `[workspace]` table at all; the root is
+discovered by walking ancestor directories for a `wkg.toml` whose
+`workspace.members` matches this manifest's path.
+<!-- TODO -->
+<!-- Point at the root explicitly with `workspace = "/path/to/wkg.toml"` if it lives outside the ancestor chain. -->
+
+### `metadata.authors`
+
+- Type: string (also accepts the legacy key `author`)
+
+Author line. Unlike `Cargo.toml`, this is a single string, not a list.
 
 ### `metadata.description`
 
@@ -60,15 +97,10 @@ Short description of the package. Emitted as the
 
 ### `metadata.license`
 
-- Type: string (SPDX expression)
-
-License identifier. Emitted as `org.opencontainers.image.licenses`.
-
-### `metadata.documentation`
-
-- Type: string (URL)
+- Type: string (SPDX expression; serialized as `licenses`)
 
-Documentation URL. Currently informational.
+License identifier. Accepts the singular `license` key as an alias. Emitted as
+`org.opencontainers.image.licenses`.
 
 ### `metadata.homepage`
 
@@ -78,15 +110,22 @@ Project homepage. Emitted as `org.opencontainers.image.url`.
 
 ### `metadata.repository`
 
-- Type: string (URL)
+- Type: string (URL; serialized as `source`)
+
+Source repository URL. Accepts `source` or `repository` on input. Emitted as
+`org.opencontainers.image.source`.
+
+### `metadata.revision`
+
+- Type: string
 
-Source repository. Emitted as `org.opencontainers.image.source`.
+Source-control revision (commit hash, tag, etc.) the package was built from.
 
 ## OCI annotation mapping
 
 When publishing to OCI via `wkg publish`, `wkg` loads the metadata from the
 wasm binary (which is automatically added to the WIT package with
-`wkg wit build` if the metadata is present in the `wkg.toml` file). The
+`wkg build` if the metadata is present in the `wkg.toml` file). The
 metadata is mapped to the following OCI annotations:
 
 | `wkg.toml` metadata field | OCI annotation                         |