diff --git a/packages/agent-spawn/README.md b/packages/agent-spawn/README.md index 0a0eca55..12f9adcd 100644 --- a/packages/agent-spawn/README.md +++ b/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. diff --git a/packages/config-extends/README.md b/packages/config-extends/README.md index 6764f70c..ae059c39 100644 --- a/packages/config-extends/README.md +++ b/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 diff --git a/packages/poe-code-config/README.md b/packages/poe-code-config/README.md index e70e0d55..c8de53da 100644 --- a/packages/poe-code-config/README.md +++ b/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: diff --git a/packages/providers/README.md b/packages/providers/README.md index e2b535de..140a657b 100644 --- a/packages/providers/README.md +++ b/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 diff --git a/packages/toolcraft/README.md b/packages/toolcraft/README.md index cac98876..e381d1a0 100644 --- a/packages/toolcraft/README.md +++ b/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 `, optional options and defaults appear in brackets like `[--limit ]`, 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: