apcore-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,109 @@ All notable changes to apcore-cli (TypeScript SDK) will be documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-04-25
+
+### Added
+
+- **Canonical clap v4 / GNU-style help formatter** (`src/canonical-help.ts`) overriding Commander's default `formatHelp` so `--help` output is byte-stable across SDK implementations. Disables terminal-width wrapping, uppercases `<PLACEHOLDER>`s, enforces `Commands:` before `Options:`, and renders `-h, --help` / `-V, --version` last with `Print help` / `Print version` descriptions.
+- **Cross-language conformance test harness** (`tests/conformance/apcli-visibility.test.ts`) now consumes the shared fixtures from the `aiperceivable/apcore-cli` spec repo (`conformance/fixtures/apcli-visibility/`). Dynamically discovers scenarios and byte-matches `--help` output against each `expected_help.txt`. Set `APCORE_CLI_SPEC_REPO` to point at a non-sibling checkout; defaults to `../apcore-cli/`.
+- **CI — spec-repo checkout**: `.github/workflows/ci.yml` now checks out `aiperceivable/apcore-cli` into `.apcore-cli-spec/` and exposes it to `pnpm test` via `APCORE_CLI_SPEC_REPO`.
+- **FE-13: Built-in command group (`apcli`)** — consolidates the 13 canonical built-in commands (`list`, `describe`, `exec`, `validate`, `init`, `health`, `usage`, `enable`, `disable`, `reload`, `config`, `completion`, `describe-pipeline`) under a single `apcli` sub-group. Invocation shifts from `<cli> list` to `<cli> apcli list`.
+  - `ApcliGroup` class + `ApcliConfig` / `ApcliMode` types, exported from `src/index.ts`.
+  - `RESERVED_GROUP_NAMES = new Set(["apcli"])` as the enforced collision surface (replaces the retired per-command `BUILTIN_COMMANDS` constant).
+  - New env var `APCORE_CLI_APCLI` — accepts `show`, `hide`, `1`, `0`, `true`, `false` (case-insensitive).
+  - New config keys (snake_case DEFAULTS): `apcli.mode`, `apcli.include`, `apcli.exclude`, `apcli.disable_env`.
+  - `ConfigResolver.resolveObject(key)` — non-leaf accessor that returns object-shaped config values without flattening.
+  - `createCli({ apcli })` option — accepts `boolean | object | ApcliGroup` to configure the built-in group surface.
+  - See [migration guide](../apcore-cli/docs/features/builtin-group.md#11-migration) for the full v0.7 → v0.8 timeline.
+- **New error-code → exit-code mappings** in `src/errors.ts` and `src/main.ts`: `DEPENDENCY_NOT_FOUND` and `DEPENDENCY_VERSION_MISMATCH` both map to exit code 44. Preserves the pre-0.19.0 exit code (`MODULE_LOAD_ERROR` = 44) for missing / version-mismatched module dependencies, now that apcore-js surfaces these through dedicated error types per PROTOCOL_SPEC §5.15.2.
+- **Binding-overlay tests** in `tests/display-helpers.test.ts`: a tmp binding YAML is written, `applyToolkitIntegration` is called, and `getDisplay()` is verified to return the overlay for a descriptor that has no baked-in `metadata.display`.
+- **`createCli({ app })` — `APCore` unified client**: `CreateCliOptions` now accepts an `app?: APCore` field. When provided, `app.registry` and `app.executor` are extracted and used in place of explicit `registry`/`executor` fields. Passing `app` together with `registry` or `executor` throws `"app is mutually exclusive with registry/executor"`.
+- `APCore` interface exported from package index. `StrategyInfo` and `StrategyStep` interfaces exported from package index.
+- `Executor` interface extended with optional `describePipeline(strategyName?: string): StrategyInfo` and `strategy?: { steps: StrategyStep[] }` fields.
+- **FE-12: Module Exposure Filtering** — Declarative control over which discovered modules are exposed as CLI commands.
+  - `ExposureFilter` class in `exposure.ts` with `isExposed(moduleId)` and `filterModules(ids)` methods.
+  - Three modes: `all` (default), `include` (whitelist), `exclude` (blacklist) with glob-pattern matching.
+  - `ExposureFilter.fromConfig(obj)` static method for loading from `apcore.yaml` `expose` section.
+  - `CreateCliOptions.expose` field accepting object or `ExposureFilter` instance.
+  - `list --exposure {exposed,hidden,all}` filter flag in discovery commands.
+  - `GroupedModuleGroup` integration: applies exposure filter during command registration.
+  - `ConfigResolver` gains `expose.*` config keys.
+  - 4-tier config precedence: `CreateCliOptions.expose` > `--expose-mode` CLI flag > env var > `apcore.yaml`.
+  - Hidden modules remain invocable via `exec <module_id>`.
+- New file: `exposure.ts`.
+
+### Changed
+
+- Built-in commands now live under the `apcli` sub-group. Pre-v0.7 invocations (`<cli> list`, `<cli> describe`, etc.) still work in **standalone mode** via deprecation shims that print a `WARNING` to stderr and forward to `apcli <name>`. Shims are not installed in embedded mode.
+- Discovery flags (`--extensions-dir`, `--commands-dir`, `--binding`) are now gated on standalone mode — they are only registered when no `registry` is injected.
+- Shell-completion generators (bash/zsh/fish) enumerate registered Commander subcommands dynamically; hardcoded command lists are gone.
+- **Dependency bump**: requires `apcore-js >= 0.19.0` (was `>= 0.18.0`) and `apcore-toolkit >= 0.5.0` (was `>= 0.4.0`). Aligns with upstream releases `apcore-js 0.19.0` (dependency graph errors, async `buildStrategyFromConfig`, auto-schema adapter chain, `BindingSchemaMissingError` rename) and `apcore-toolkit 0.5.0` (`BindingLoader`, `ScannedModule.display`, `apcore-toolkit/browser` subpath).
+- **Placeholder types in `src/cli.ts` realigned with real apcore-js shapes.** `PipelineTrace` / `StepTrace` / `PreflightResult` / `StrategyStep` now use camelCase (`strategyName`, `totalDurationMs`, `durationMs`, `skipReason`, `requiresApproval`, `timeoutMs`) matching the apcore-js runtime object shape. `Executor.describePipeline` is typed as `(): StrategyInfo` (zero arguments — the previous `describePipeline?(strategyName?: string)` signature declared an argument that the real apcore-js method ignores). `Executor.strategy` renamed to `Executor.currentStrategy` to match the upstream getter.
+- **`--trace` output now reads the correct runtime fields.** `main.ts` previously read `trace.strategy_name` / `trace.total_duration_ms` / `s.duration_ms` / `s.skip_reason` (snake_case) from the camelCase `PipelineTrace` returned by apcore-js, so those values surfaced as `undefined` at runtime. Now reads `strategyName` / `totalDurationMs` / `durationMs` / `skipReason` correctly. JSON output keys remain snake_case to preserve the cross-language CLI output contract.
+- **`formatPreflightResult` now reads `result.requiresApproval`** (was `result.requires_approval`). The JSON output key remains `requires_approval`.
+- **`MAX_MODULE_ID_LENGTH` 128 → 192**: `validateModuleId()` now enforces a 192-character limit for module IDs, up from 128, to accommodate Java/.NET deep-namespace FQN-derived IDs (PROTOCOL_SPEC §2.7 spec 1.6.0-draft).
+- **`Executor.describePipeline()` returns `StrategyInfo`**: `describe-pipeline` command in `strategy.ts` now calls `executor.describePipeline(strategyName)` and consumes the returned `StrategyInfo` object (`name`, `stepCount`, `stepNames`, `description`). Pipeline header format updated to `Pipeline: ${info.name} (${info.stepCount} steps)`. Step metadata (Pure/Removable/Timeout columns) sourced from `executor.strategy.steps` (`pure: boolean`, `removable: boolean`, `timeoutMs: number`). Falls back to static preset table when `describePipeline` is not available.
+
+### Deprecated
+
+- Root-level v0.6 built-in commands continue to work in standalone mode but emit a `WARNING` and forward to `apcli <name>`. **Scheduled for removal in v0.8.**
+
+### Removed
+
+- The per-command `BUILTIN_COMMANDS` constant and its re-export from `src/index.ts`. Replaced by `RESERVED_GROUP_NAMES`.
+- Monolithic registrars `registerDiscoveryCommands`, `registerSystemCommands`, `registerShellCommands` — replaced by per-subcommand exports invoked through `ApcliGroup`.
+
+### Fixed
+
+- **`describe-pipeline --strategy <name>` now works for non-current strategies.** Previously the command called `executor.describePipeline(strategyName)` — the real apcore-js signature takes no arguments and always returns info for the executor's *current* strategy, so all `--strategy` values produced identical output. `src/strategy.ts` now uses a two-step lookup: if the requested name matches the current strategy, use `describePipeline()`; otherwise fall back to the static `Executor.listStrategies()` (reached via `executor.constructor.listStrategies`) to introspect other registered strategies.
+- **`--binding <path>` flag now actually applies display overlay.** `applyToolkitIntegration` previously instantiated a `DisplayResolver` and discarded it. The implementation now uses apcore-toolkit 0.5.0's `BindingLoader` + `DisplayResolver` pipeline to parse the binding YAML, resolve the sparse overlay, and populate a module-level binding display map. `display-helpers.ts#getDisplay` consults the map as a fallback when the descriptor itself has no `metadata.display`, so `cli.alias` / `cli.description` / tags from `.binding.yaml` are now honored by `list`, `describe`, and command help output. New exports: `lookupBindingDisplay(moduleId)` and `clearBindingDisplayMap()` from `src/main.ts`.
+
+### Breaking
+
+- Reserved-name enforcement is now a **hard exit 2** when a module's explicit group, auto-group prefix, or top-level name/alias equals `apcli`. Previously this was warn-and-drop.
+
+---
+
+## [0.6.0] - 2026-04-06
+
+### Changed
+
+- **Dependency bump**: requires `apcore-js >= 0.17.1` (was `>= 0.15.1`). Adds Execution Pipeline Strategy, Config Bus enhancements, Pipeline v2 declarative step metadata, `minimal` strategy preset.
+- **Schema parser**: Required schema properties now correctly enforced at Commander option level (was silently optional).
+- `checkApproval()` now accepts `timeout` parameter instead of hardcoded 60s.
+
+### Added
+
+- **FE-11: Usability Enhancements** — 11 new capabilities:
+  - `--dry-run` preflight mode. Standalone `validate` command via `registerValidateCommand()`.
+  - System management commands: `health`, `usage`, `enable`, `disable`, `reload`, `config get`/`config set` in `system-cmd.ts`. Graceful no-op when system modules unavailable.
+  - Enhanced error output: `emitErrorJson()` / `emitErrorTty()` with structured guidance fields.
+  - `--trace` pipeline visualization.
+  - `CliApprovalHandler` class implementing apcore `ApprovalHandler` protocol. `--approval-timeout`, `--approval-token` flags.
+  - `--stream` JSONL output.
+  - Enhanced `list` command: `--search`, `--status`, `--annotation`, `--sort`, `--reverse`, `--deprecated`, `--deps`, `--flat`.
+  - `--strategy` selection: `standard`, `internal`, `testing`, `performance`, `minimal`. `describe-pipeline` command in `strategy.ts`.
+  - Output format extensions: `--format csv|yaml|jsonl`, `--fields` dot-path field selection.
+  - Multi-level grouping: `groupDepth` parameter in `resolveGroup()`.
+  - Custom command extension: `CreateCliOptions.extraCommands` with collision detection.
+- `Executor` interface extended with optional `validate()`, `callWithTrace()`, `stream()`, `call()` methods.
+- `PreflightResult`, `PreflightCheck`, `PipelineTrace`, `PipelineTraceStep` types exported.
+- New error code: `CONFIG_ENV_MAP_CONFLICT` in `EXIT_CODES`.
+- Config defaults: `cli.approval_timeout` (60), `cli.strategy` ("standard"), `cli.group_depth` (1).
+- New files: `system-cmd.ts`, `strategy.ts`.
+
+---
+
+## [0.5.1] - 2026-04-03
+
+### Added
+- **Pre-populated registry support** — `createCli()` accepts a `CreateCliOptions` object with optional `registry` and `executor` fields. When a pre-populated `Registry` is provided, filesystem discovery is skipped entirely. This enables frameworks that register modules at runtime to generate CLI commands from their existing registry without requiring an extensions directory.
+- `CreateCliOptions` interface exported from package index.
+- Passing `executor` without `registry` throws an error.
+
+---
+
 ## [0.4.0] - 2026-03-29
 
 ### Added

package/LICENSE

@@ -1,21 +1,17 @@
-MIT License
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright (c) 2026 AI Perceivable
+   Copyright 2024 aiperceivable <tercel.yi@gmail.com>
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+       http://www.apache.org/licenses/LICENSE-2.0
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -8,7 +8,7 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org)
-[![Tests](https://img.shields.io/badge/tests-183%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-275%2B%20passed-brightgreen.svg)]()
 
 | | |
 |---|---|
@@ -49,7 +49,14 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pnpm add apcore-cli apcore-js
 ```
 
-Requires Node.js 18+ and `apcore-js >= 0.14.0`.
+Requires Node.js 18+ and `apcore-js >= 0.19.0`.
+
+**Optional:** install `apcore-toolkit` (>=0.5.0) to enable display overlay and registry writer integration via `applyToolkitIntegration`, `DisplayResolver`, and `RegistryWriter`.
+
+```bash
+pnpm add apcore-cli apcore-js
+pnpm add -D apcore-toolkit  # optional, for display overlay / registry writer
+```
 
 ## Quick Start
 
@@ -73,26 +80,54 @@ All modules are auto-discovered. CLI flags are auto-generated from each module's
 ```typescript
 import { createCli } from "apcore-cli";
 
-// Build the CLI from your registry
+// Build the CLI from an extensions directory (auto-discovers modules)
 const cli = createCli("./extensions");
 cli.parse(process.argv);
 ```
 
-Or use the `LazyModuleGroup` directly with Commander:
+#### Pre-populated registry
+
+Frameworks that register modules at runtime can pass a pre-populated `Registry` directly via `CreateCliOptions`, skipping filesystem discovery entirely:
 
 ```typescript
-import { LazyModuleGroup, buildModuleCommand } from "apcore-cli";
-import { Registry, Executor } from "apcore-js";
+import { createCli } from "apcore-cli";
+import type { CreateCliOptions } from "apcore-cli";
+
+// registry and executor are already populated by your framework
+const cli = createCli({
+  registry,
+  executor,
+  progName: "myapp",
+});
+cli.parse(process.argv);
+```
 
-const registry = new Registry("./extensions");
-registry.discover();
-const executor = new Executor(registry);
+Or wire the `createCli` options-object form directly with a runtime-supplied registry/executor:
+
+```typescript
+import { createCli } from "apcore-cli";
 
-const group = new LazyModuleGroup(registry, executor);
-const cmd = group.getCommand("math.add");
-cmd?.parse(process.argv);
+async function main() {
+  // Obtain registry/executor from your apcore-js setup
+  // (e.g., via ExtensionsLoader or your framework's module discovery).
+  // See apcore-js docs for the exact bootstrap API.
+  const { registry, executor } = await bootstrapApcoreRuntime("./extensions");
+
+  const cli = createCli({
+    registry,
+    executor,
+    progName: "myapp",
+    // expose: { mode: "include", include: ["admin.*"] },
+    // extraCommands: [customCmd1, customCmd2],
+  });
+  cli.parse(process.argv);
+}
+
+main();
 ```
 
+> **Known gap:** The `Registry`, `Executor`, and `ModuleDescriptor` types re-exported by `apcore-cli` are currently **local placeholder interfaces** pending upstream export from `apcore-js`. Direct construction (`new Registry(...)` / `new Executor(registry)`) is **not supported** at this version. Structural typing allows runtime apcore-js objects to satisfy these interfaces, so `createCli({ registry, executor })` works when you pass in objects produced by your apcore-js runtime.
+
 ## Integration with Existing Projects
 
 ### Typical apcore project structure
@@ -151,15 +186,66 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 | `--verbose` | | Show all options in help (including built-in apcore options) |
 | `--man` | | Output man page in roff format (use with `--help`) |
 
-### Built-in Commands
+### Built-in Commands (the `apcli` group)
+
+Starting in **v0.7.0**, all built-in commands live under an `apcli` sub-group
+(see the `RESERVED_GROUP_NAMES` collision surface in `src/builtin-group.ts`).
+Invocation:
+
+```bash
+apcore-cli apcli list
+apcore-cli apcli describe math.add
+apcore-cli apcli exec math.add --a 5 --b 10
+```
+
+> **Migration note (v0.7):** Root-level invocations (`apcore-cli list`, `apcore-cli describe`, …) still work in **standalone mode** but emit a deprecation
+> `WARNING` and are removed in v0.8. Embedded integrations (host CLIs that
+> inject a `registry`) never had root-level built-ins in the first place and
+> see no warnings. See the full migration timeline in the spec repo:
+> [`docs/features/builtin-group.md §11 Migration`](../apcore-cli/docs/features/builtin-group.md#11-migration).
+
+The canonical 13 `apcli` subcommands:
+
+**Module invocation & discovery**
+
+| Command | Description |
+|---------|-------------|
+| `apcli list` | List available modules with search, status, tag/annotation filters, sort, and dependency inspection (see `registerListCommand` in `src/discovery.ts`) |
+| `apcli describe <module_id>` | Show full module metadata, schemas, and annotations (see `registerDescribeCommand` in `src/discovery.ts`) |
+| `apcli describe-pipeline <module_id>` | Inspect the execution pipeline for a module (strategies, hooks, middleware; see `registerPipelineCommand` in `src/strategy.ts`) |
+| `apcli exec <module_id>` | Internal routing alias for module execution (see `registerExecCommand` in `src/discovery.ts`) |
+| `apcli usage <module_id>` | Show usage examples and flag hints for a module (see `registerUsageCommand` in `src/system-cmd.ts`) |
+
+**System management**
 
 | Command | Description |
 |---------|-------------|
-| `list` | List available modules with optional tag filtering |
-| `describe <module_id>` | Show full module metadata and schemas |
-| `exec <module_id>` | Internal routing alias for module execution |
-| `completion <shell>` | Generate shell completion script (bash/zsh/fish) |
-| `man <command>` | Generate man page in roff format |
+| `apcli config` | Inspect effective configuration and precedence (see `registerConfigCommand` in `src/system-cmd.ts`) |
+| `apcli health` | Run health checks on registry, executor, config, and auth (see `registerHealthCommand` in `src/system-cmd.ts`) |
+| `apcli reload` | Reload registry / rediscover extensions (see `registerReloadCommand` in `src/system-cmd.ts`) |
+| `apcli enable <module_id>` | Enable a disabled module (see `registerEnableCommand` in `src/system-cmd.ts`) |
+| `apcli disable <module_id>` | Disable a module without removing it (see `registerDisableCommand` in `src/system-cmd.ts`) |
+
+**Workflow**
+
+| Command | Description |
+|---------|-------------|
+| `apcli init` | Scaffold a starter `apcore.yaml` / extensions layout (see `registerInitCommand` in `src/init-cmd.ts`) |
+| `apcli validate` | Validate modules and configuration against JSON Schema (see `registerValidateCommand` in `src/discovery.ts`) |
+
+**Shell integration**
+
+| Command | Description |
+|---------|-------------|
+| `apcli completion <shell>` | Generate shell completion script for bash / zsh / fish (see `registerCompletionCommand` in `src/shell.ts`) |
+| `man [command]` (root) | Generate a man page in roff format for a single command or the whole program (see `configureManHelp` in `src/shell.ts`). Stays at the root (meta-command). |
+
+#### Standalone vs. embedded surfaces
+
+| Mode | Invocation | Notes |
+|------|------------|-------|
+| **Standalone** (`apcore-cli`) | `apcore-cli apcli <subcommand>` | Discovery flags (`--extensions-dir`, `--commands-dir`, `--binding`) are registered. Legacy root-level built-ins are kept as deprecation shims. |
+| **Embedded** (`createCli({ registry, … })`) | `<host-cli> apcli <subcommand>` | Discovery flags are gated off (injected registry already supplies modules). No legacy shims — embedded hosts are new territory. |
 
 ### Module Execution Options
 
@@ -170,11 +256,32 @@ When executing a module (e.g. `apcore-cli math.add`), these built-in options are
 | `--input -` | Read JSON input from STDIN |
 | `--yes` / `-y` | Bypass approval prompts |
 | `--large-input` | Allow STDIN input larger than 10MB |
-| `--format` | Output format: `json` or `table` |
+| `--format <fmt>` | Output format: `json`, `table`, `csv`, `yaml`, or `jsonl` |
 | `--sandbox` | Run module in subprocess sandbox (not yet implemented — always hidden) |
+| `--dry-run` | Run preflight checks (schema, ACL, approval) without executing (FE-11) |
+| `--trace` | Emit execution pipeline trace (strategy, hooks, middleware timings) |
+| `--stream` | Stream results line-by-line for stream-capable modules |
+| `--strategy <name>` | Override execution strategy: `standard`, `internal`, `testing`, `performance`, or `minimal` |
+| `--fields <csv>` | Select output fields via dot-path notation (e.g. `result.sum,meta.duration`) |
+| `--approval-timeout <seconds>` | Override approval timeout (default `60`) |
+| `--approval-token <token>` | Provide a pre-obtained approval token (bypasses interactive prompt) |
 
 Schema-generated flags (e.g. `--a`, `--b`) are added automatically from the module's `input_schema`.
 
+#### `list` command flags (v0.6.0)
+
+The `list` command supports enhanced filtering and inspection flags:
+
+| Option | Description |
+|--------|-------------|
+| `--search <query>` | Fuzzy search across module IDs, descriptions, and annotations |
+| `--status <state>` | Filter by status (e.g. `enabled`, `disabled`, `deprecated`) |
+| `--annotation <key=value>` | Filter by an annotation key/value pair |
+| `--sort <field>` | Sort by `name`, `status`, or other indexed fields |
+| `--reverse` | Reverse sort order |
+| `--deprecated` | Include deprecated modules in the output |
+| `--deps` | Show dependency graph for each module |
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -210,6 +317,9 @@ apcore-cli uses a 4-tier configuration precedence:
 | `APCORE_AUTH_API_KEY` | API key for remote registry authentication | *(unset)* |
 | `APCORE_CLI_SANDBOX` | Set to `1` to enable subprocess sandboxing | *(unset)* |
 | `APCORE_CLI_HELP_TEXT_MAX_LENGTH` | Maximum characters for CLI option help text before truncation | `1000` |
+| `APCORE_CLI_APPROVAL_TIMEOUT` | Default approval prompt timeout in seconds | `60` |
+| `APCORE_CLI_STRATEGY` | Default execution strategy (`standard`, `internal`, `testing`, `performance`, `minimal`) | `standard` |
+| `APCORE_CLI_GROUP_DEPTH` | Maximum nesting depth when rendering grouped module command trees | `2` |
 
 ### Config File (`apcore.yaml`)
 
@@ -222,6 +332,9 @@ sandbox:
   enabled: false
 cli:
   help_text_max_length: 1000
+  approval_timeout: 60      # seconds
+  strategy: standard        # standard | internal | testing | performance | minimal
+  group_depth: 2            # grouped-module command-tree nesting depth
 ```
 
 ## Features
@@ -234,7 +347,7 @@ cli:
 - **TTY-adaptive output** -- rich tables for terminals, JSON for pipes (configurable via `--format`)
 - **Approval gate** -- TTY-aware HITL prompts for modules with `requires_approval: true`, with `--yes` bypass and 60s timeout
 - **Schema validation** -- inputs validated against JSON Schema before execution, with `$ref`/`allOf`/`anyOf`/`oneOf` resolution
-- **Security** -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing
+- **Security** -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing (stub — not yet runnable)
 - **Shell completions** -- `apcore-cli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
 - **Man pages** -- `apcore-cli man <command>` for single commands, or `--help --man` for a complete program man page. `configureManHelp()` provides one-line integration for downstream projects
 - **Documentation URL** -- `setDocsUrl()` adds doc links to help footers and man pages
@@ -267,7 +380,7 @@ apcore-cli (the adapter)
     +-- approval             TTY-aware HITL approval
     +-- output               TTY-adaptive JSON/table output
     +-- AuditLogger          JSON Lines execution logging
-    +-- Sandbox              Subprocess isolation
+    +-- Sandbox              Subprocess isolation (stub — not yet runnable)
     |
     v
 apcore Registry + Executor (your modules, unchanged)
@@ -277,20 +390,38 @@ apcore Registry + Executor (your modules, unchanged)
 
 **Classes:** `LazyModuleGroup`, `ConfigResolver`, `AuthProvider`, `ConfigEncryptor`, `AuditLogger`, `Sandbox`
 
+**Interfaces:** `CreateCliOptions`, `Registry`, `Executor`, `ModuleDescriptor`
+
 **Functions:** `createCli`, `main`, `buildModuleCommand`, `validateModuleId`, `collectInput`, `schemaToCliOptions`, `reconvertEnumValues`, `resolveRefs`, `checkApproval`, `resolveFormat`, `formatModuleList`, `formatModuleDetail`, `formatExecResult`, `registerDiscoveryCommands`, `registerShellCommands`, `setAuditLogger`, `getAuditLogger`, `setVerboseHelp`, `setDocsUrl`, `buildProgramManPage`, `configureManHelp`, `exitCodeForError`, `mapType`, `extractHelp`, `truncate`
 
 **Errors:** `ApprovalTimeoutError`, `ApprovalDeniedError`, `AuthenticationError`, `ConfigDecryptionError`, `ModuleExecutionError`, `ModuleNotFoundError`, `SchemaValidationError`
 
 ## Development
 
+The conformance suite under `tests/conformance/` reads shared fixtures from
+the **spec repo** (`aiperceivable/apcore-cli`). Clone it as a sibling of
+this repo, or point `APCORE_CLI_SPEC_REPO` at an existing checkout:
+
 ```bash
+# One-time: clone both repos side by side
+git clone https://github.com/aiperceivable/apcore-cli.git
 git clone https://github.com/aiperceivable/apcore-cli-typescript.git
+
 cd apcore-cli-typescript
 pnpm install
-pnpm test                        # 183 tests
+pnpm test                        # reads fixtures from ../apcore-cli/conformance/
 pnpm build                       # compile TypeScript
 ```
 
+Alternative layout (spec repo checked out elsewhere):
+
+```bash
+export APCORE_CLI_SPEC_REPO=/path/to/apcore-cli
+pnpm test
+```
+
+CI does this automatically — see `.github/workflows/ci.yml`.
+
 ## License
 
 Apache-2.0