docs: refresh recent behavior notes

packages/agent-spawn/README.md

@@ -73,4 +73,4 @@ vi.mock("@poe-code/agent-spawn", spawnMock.factory);
 
 ## Environment variables
 
-This package does not expose public environment variables. It inherits `process.env` for child processes and may add agent-specific env overrides from declarative spawn config, such as `GOOSE_MODE` for Goose modes or `OPENCODE_CONFIG_CONTENT` for OpenCode MCP injection.
+This package does not expose public environment variables. It inherits `process.env` for child processes and may add agent-specific env overrides from declarative spawn config, such as `GOOSE_MODE` for Goose modes, `GOOSE_DISABLE_KEYRING=1` for Goose file-backed credentials, or `OPENCODE_CONFIG_CONTENT` for OpenCode MCP injection.

packages/config-extends/README.md

@@ -1,10 +1,22 @@
 # @poe-code/config-extends
 
-Shared document-inheritance types for layered config resolution.
+Shared document-inheritance utilities for layered config resolution.
 
 ## API
 
-Currently this package exposes shared TypeScript types only.
+- `resolve(chain, options)`: resolves exactly one document layer with surrounding data and base layers.
+- `findBase(name, basePaths, fs)`: discovers a base document by name across configured base paths.
+- `parseDocument(content, filePath)`: parses a document and separates inheritance metadata from data.
+- `mergeLayers(layers)`: merges data layers and tracks the source of each resolved key.
+
+## Resolution behavior
+
+A chain must contain exactly one document layer. Data layers before and after the document are merged around the resolved document, and base layers define directories that can be inherited from.
+
+- Documents that set `extends: true` must resolve a base and still report circular inheritance as an error.
+- With `autoExtend: true`, documents that do not set `extends` try to inherit from matching bases automatically.
+- Optional auto-extend discovery is ignored when it finds the document itself, so a document can safely live in a configured base directory without creating a circular extends error.
+- Prompt values can compose with the `{{yield}}` token across resolved base layers.
 
 ## Environment variables
 

packages/poe-code-config/README.md

@@ -30,6 +30,8 @@ Project config is read as an override on top of global config.
 - Keys inside a scope are merged.
 - When the same key exists in both places, the project value wins.
 - Missing or `undefined` project keys do not remove global values.
+- If the project config path resolves to the global config path, only the global document is read and no self-merge is attempted.
+- Project config reads auto-extend from the global config directory, but self-discovered optional bases are ignored by `@poe-code/config-extends`.
 
 Example:
 

packages/providers/README.md

@@ -54,9 +54,14 @@ const apiKey = await apiKeyAuthStrategy.resolveCredential(anthropic, { secretSto
 
 `ProviderRegistry.login()` resolves API keys in this order:
 
-1. Explicit `options.apiKey`
-2. The provider's declared `auth.envVar` from `context.envVars`
-3. `promptForSecret`
+1. `context.resolvePreferredLogin` when the provider declares `auth.preferredLogin`
+2. Explicit `options.apiKey`
+3. The provider's declared `auth.envVar` from `context.envVars`
+4. `promptForSecret`
+
+`preferredLogin` is optional. It lets a provider prefer a custom login flow, such as OAuth,
+while still storing the resulting API key through the same provider secret store. If no
+`resolvePreferredLogin` callback is supplied, login falls back to the generic API-key flow.
 
 `ProviderRegistry.isLoggedIn()` also treats a non-empty declared env var as logged in,
 matching what `login()` would use in CI.
@@ -71,3 +76,12 @@ and `LoginContext.envVars`.
 
 No runtime configuration; everything is declared per-provider via the `AuthProvider`
 manifest.
+
+Provider manifest options:
+
+- `id`, `label`, `summary`, `baseUrl`, and `supportsAgents`
+- `auth.kind: "api-key"` with `envVar`, `storageKey`, `prompt`, and optional
+  `preferredLogin: "oauth"`
+- `auth.kind: "oauth"` for OAuth-native providers
+- `env` for provider-specific environment values derived from literals, credentials, base
+  URLs, or provider fields

packages/toolcraft/README.md

@@ -178,6 +178,8 @@ The same `root` flows into all three. No duplication.
 
 **Tree**: the `root` group is a `defineGroup` whose children are commands and sub-groups. Any depth. CLI flags, MCP tool names, and SDK methods are derived from the path.
 
+**CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters stay unbracketed even when the underlying schema field is optional. Command-specific `--help` still shows the detailed parameter table.
+
 ## Secrets
 
 Declare env-backed secrets on a command or group. Toolcraft reads `process.env` at command-run time and passes the values to the handler: