From b525caf2858f0364c2f6e4eccec5e47191626b38 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Wed, 29 Apr 2026 00:31:43 +0000 Subject: [PATCH 1/4] docs: document toolcraft group help parameters --- packages/toolcraft/README.md | 2 ++ 1 file changed, 2 insertions(+) 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: From 772af448da4c7f23337d42ee92d01d97514c9757 Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Fri, 1 May 2026 00:31:05 +0000 Subject: [PATCH 2/4] docs: update provider and goose auth notes --- packages/agent-spawn/README.md | 2 +- packages/providers/README.md | 20 +++++++++++++++++--- 2 files changed, 18 insertions(+), 4 deletions(-) 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/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 From 888fc8478d1ec64ce6c882655732820b6145557f Mon Sep 17 00:00:00 2001 From: "poe-code-agent[bot]" <254571472+poe-code-agent[bot]@users.noreply.github.com> Date: Mon, 4 May 2026 00:27:33 +0000 Subject: [PATCH 3/4] docs: document config self-discovery handling --- packages/config-extends/README.md | 16 ++++++++++++++-- packages/poe-code-config/README.md | 2 ++ 2 files changed, 16 insertions(+), 2 deletions(-) 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: From 1e78578924a35241759256ad99cb39969ed49600 Mon Sep 17 00:00:00 2001 From: Kamil Jopek Date: Tue, 5 May 2026 11:51:32 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: poe-code-agent[bot] <254571472+poe-code-agent[bot]@users.noreply.github.com> --- packages/toolcraft/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/toolcraft/README.md b/packages/toolcraft/README.md index e381d1a0..e075b19a 100644 --- a/packages/toolcraft/README.md +++ b/packages/toolcraft/README.md @@ -178,7 +178,7 @@ 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. +**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 render as positional tokens like `` or `[name]` depending on whether they are required. Command-specific `--help` still shows the detailed parameter table. ## Secrets