apcore-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{apcore_cli-0.7.0 → apcore_cli-0.8.0}/CHANGELOG.md

@@ -6,6 +6,208 @@ 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.8.0] - 2026-05-08
+
+### Removed
+
+- **D9-001 — FE-13 §11.2 deprecation shims removed**. The 13 hidden root-level
+  shims (`list`, `describe`, `exec`, `init`, `validate`, `health`, `usage`,
+  `enable`, `disable`, `reload`, `config`, `completion`, `describe-pipeline`)
+  installed by `_register_deprecation_shims` and the `__is_deprecation_shim__`
+  collision-handling path in `extra_commands` wiring have been deleted along
+  with the `_DEPRECATED_ROOT_COMMANDS` table. Use the canonical
+  `apcli <command>` paths instead. Calls like `apcore-cli list` now exit
+  non-zero with Click's "No such command" message — the warning window
+  documented as "removed in v0.8" is closed.
+
+### Deprecated
+
+- **`CliModuleNotFoundError` alias** — the symbol still resolves to
+  `ModuleNotFoundError` (see D1-002 in Changed) but is scheduled for
+  removal in v0.10.0. Update imports to
+  `from apcore_cli import ModuleNotFoundError`.
+
+### Security
+
+- **D10-001 — `Sandbox` per-stream output cap** (`sandbox.py:155`). The previous
+  implementation summed `stdout + stderr` against a single `max_output_bytes`
+  budget — a runaway child writing only to stderr could starve the stdout
+  budget and vice versa, and the diagnostic on overflow did not name the
+  offending stream. Each stream now has an independent byte budget matching
+  Rust and TypeScript; the overflow error names the stream that tripped the
+  cap.
+- **D11-W2 — `Sandbox` switched from `subprocess.run` to `subprocess.Popen`
+  with threaded chunked reads** (`sandbox.py:155`). `capture_output=True`
+  buffered the entire child stdio into parent memory before the cap was
+  checked, so a child producing GBs of output could OOM the parent before
+  the limit was enforced. The new implementation streams stdout/stderr
+  through reader threads with bounded buffers and kills the child as soon
+  as either stream exceeds its cap. Memory consumption is now bounded by
+  `2 × max_output_bytes` regardless of child output volume.
+- **D11-003 — `ConfigEncryptor` v1 decryption honours
+  `APCORE_CLI_CONFIG_PASSPHRASE`** (`config_encryptor.py:128`). `_aes_decrypt_v1`
+  hard-coded the host:user material, so v1 ciphertext encrypted by the Rust
+  or TypeScript SDKs under a passphrase failed to decrypt on Python.
+  Decryption now tries the passphrase-derived key first when the env var is
+  set, falling back to host:user material — matching TypeScript
+  `aesDecryptV1`. Cross-SDK config bundles are now portable.
+- **D11-008 — `AuditLogger._get_user` fallback chain now includes `LOGNAME`**
+  (`audit.py:66`). The canonical chain per `security.md` (D11-W1) is
+  `getlogin → pwd.getpwuid → USER → LOGNAME → USERNAME → unknown`. Python
+  previously skipped `LOGNAME`, so audit-log `user` fields diverged from
+  Rust/TS on hosts where only `LOGNAME` is set (some container runtimes,
+  cron jobs).
+
+### Added
+
+- **`builtin_group_name="apcli"` kwarg on `create_cli`** — downstream branded CLIs that embed apcore-cli can now expose the built-in commands under a custom namespace (e.g. `mycorp-cli admin health` instead of `mycorp-cli apcli health`). `ApcliGroup` gains a `name` parameter (with property accessor) threaded through `from_cli_config` / `from_yaml` / `_build`. Default `"apcli"` is unchanged. Validated against `/^[a-z][a-z0-9_-]*$/`; invalid values exit 2. `RESERVED_GROUP_NAMES` collision check now consults `GroupedModuleGroup._reserved_group_names` (instance attribute, defaults to the static frozenset; factory replaces with the resolved name). Env var `APCORE_CLI_APCLI` and config keys `apcli.*` deliberately do NOT rename — they are apcore-cli-internal toggles, not user-facing. Cross-SDK parity with TypeScript `createCli({ builtinGroupName })`. New `DEFAULT_BUILTIN_GROUP_NAME` constant exported from `apcore_cli.builtin_group`.
+- **`_exit_on_system_error(e)` helper in `system_cmd.py`** — centralizes the canonical error→exit-code mapping for system-management subcommands, replacing 7 sites that previously used bare `sys.exit(1)` (audit D11-B-002, see Fixed).
+- **5 new tests in `tests/test_builtin_group.py`** — `TestBuiltinGroupRename` class covers default name, custom name via both factories, validation of valid/invalid name shapes (5 valid + 6 invalid forms each).
+- **D1-001 — 13 `register_*_command` factories + `configure_man_help`
+  re-exported from `apcore_cli` package root**. Embedders that compose
+  their own root command tree no longer need to reach into private
+  submodules (`apcore_cli.commands.list_cmd`, etc.). All TS/Rust
+  `register_*` counterparts now have a Python public-API equivalent.
+- **D1-003 — `apcore_cli.exit_codes` module** with 24 `EXIT_*` integer
+  constants, an `EXIT_CODES` mapping dict, and an `exit_code_for_error()`
+  helper. Mirrors TS `errors.ts` `EXIT_CODES` + `exitCodeForError` and
+  Rust `src/lib.rs` `EXIT_*` constants. Embedders can now map exceptions
+  to documented exit codes without re-implementing the table.
+- **D1-007 — `format_module_list`, `format_module_detail`,
+  `resolve_format` re-exported from package root**. The
+  output-formatter feature spec declares these as Contracts; previously
+  only `format_exec_result` was public.
+- **D1-W1 — `APCLI_SUBCOMMAND_NAMES` re-exported from `apcore_cli`**.
+  Matches Rust `lib.rs` and is now in `__all__` for static-analysis
+  tooling.
+- **D1-W2 — `ApcliConfig` TypedDict** added to the public surface,
+  mirroring the TypeScript type alias and Rust struct so embedders have
+  a static contract for the `apcli.*` config block.
+- **D1-W3 — `register_config_namespace()` helper + module-level
+  `DEFAULTS` constant** in `config.py`. The package still registers the
+  namespace at import time, but embedders can now invoke the helper
+  explicitly (parity with `apcore-cli-typescript`).
+- **D1-W5 — Core dispatcher embedder API re-exported from package
+  root**: `build_module_command`, `collect_input`, `validate_module_id`,
+  `set_audit_logger`, `set_verbose_help`, `set_docs_url`. Embedders no
+  longer have to import from `apcore_cli.cli` directly. Matches Rust
+  `lib.rs:186-190` and TS `index.ts:18`. New `tests/test_public_api.py`
+  pins the surface against future drift.
+- **D1-info-1 — typed `ApcliGroupError` exception**
+  (`builtin_group.py:107`). Cross-SDK parity with Rust `ApcliGroupError`;
+  embedders previously had no stable error class to match on for
+  built-in-group config validation. `ApcliGroupError(ValueError)`
+  preserves backwards compat — existing `except ValueError` callers
+  still catch it. The invalid-name regex check in `__init__` now raises
+  `ApcliGroupError`. Re-exported from `apcore_cli`.
+
+### Fixed
+
+- **D11-B-006 — `discovery.py:208` sort direction inverted**. `apcli list --sort calls|errors|latency` now defaults to DESCENDING (highest call count first) per spec T-LST-04, matching Rust `discovery.rs:209` and TypeScript `discovery.ts:186`. Previously the user's raw `--reverse` flag (default False) was passed directly to `sort_modules_by_usage(..., reverse=...)`, producing ASCENDING output by default — the inverse of the spec. Fix passes `reverse=not reverse` for the data path AND adds a re-sort at the call site for the audit-log-empty fallback so id-fallback continues to default ASCENDING per spec.
+- **D11-B-002 — `system_cmd.py` collapsed every error to exit 1**. The 7 `except Exception as e: sys.exit(1)` sites bypassed Python's own `_ERROR_CODE_MAP` (canonical 44/46/47/77) — scripted operators could not distinguish "module not found" from "ACL denied" from generic failure. All 7 sites now route through the new `_exit_on_system_error(e)` helper which calls `exit_code_for_error(e)` from `apcore_cli.exit_codes`. The 4 audit-log entries previously hardcoding `exit_code=1` now log the resolved code.
+- **D11-NEW-005 — RESERVED_PROPERTY_NAMES no longer raises generic `ValueError`**. `schema_to_click_options` previously raised `ValueError` when a schema property collided with a built-in CLI option — opaque to scripted callers and inconsistent with the neighbour flag-collision branch (which already exited 48). Now writes a user-facing `Error:` line to stderr and calls `sys.exit(48)` per spec, matching TS `process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF)` and Rust `CliError::SchemaParserFailure → EXIT_SCHEMA_CIRCULAR_REF`. Tests tightened from `pytest.raises((ValueError, Exception))` to `pytest.raises(SystemExit)` with `code == 48` assertion.
+- **D9-NEW-002 — `ref_resolver.py` `allOf required` not deduplicated**. `_resolve_node`'s `allOf` branch concatenated parent `required` + each branch's `required` without dedup, producing duplicate entries in the merged schema's `required` array. JSON Schema validators ignore duplicates so observable validation behaviour was unchanged, but cross-SDK byte-comparison tooling (and the `anyOf`/`oneOf` paths, which already deduped) flagged the divergence. Fix: explicit seen-set dedup preserving first-seen order, matching TS `[...new Set(...)]` and Rust `merge_allof`.
+- **D10-003 — `build_module_command` leaked `RefResolverError`
+  tracebacks** (`cli.py:538`). The `resolve_refs` catch clause re-raised
+  unchanged, so callers saw a Python traceback instead of a clean
+  documented exit code. Now translates `CircularRefError` /
+  `MaxDepthExceededError` to `sys.exit(48)` and `UnresolvableRefError`
+  (plus generic `RefResolverError`) to `sys.exit(45)`, mirroring
+  `schema_parser.py:111` and the Rust/TS contracts.
+- **D11-NEW-003 — `ref_resolver` `max_depth` over-counted plain nested
+  `properties`** (`ref_resolver.py`). `_resolve_node` previously
+  incremented `depth + 1` when recursing into nested `properties`
+  values, so a schema with >32 levels of nested objects (no `$ref` at
+  all) was rejected with `MaxDepthExceededError`. The spec wording is
+  "Maximum `$ref` resolution recursion depth" — `$ref` hops along a
+  single chain, not total stack depth. `depth` is now only incremented
+  on `$ref` traversal, aligning with Rust `ref_resolver.rs:297`. Also
+  adds 4 regression tests for `anyOf`/`oneOf` sibling-required
+  preservation and `anyOf` overlap dedup.
+- **D10-info-1 — `APCORE_CLI_APCLI` env var not trimmed on read**
+  (`builtin_group.py:414`). Spec invariant 2 requires the parser to be
+  case-insensitive AND trim-on-read. Surrounding whitespace previously
+  caused a silent Tier-3/Tier-4 fall-through. Now strips before
+  lowercasing, matching Rust/TS.
+- **D11-010 — `AuditLogger` write-failure warnings deduplicated**
+  (`audit.py:55`). Previously warned on every failed write, flooding
+  logs when an audit dir is unwritable. An instance flag now gates the
+  warning so it fires once per logger instance, matching the TS
+  `writeFailureWarned` flag.
+
+### Changed
+
+- **`apcli system *` and `apcli strategy describe-pipeline` `--format` choices**
+  expanded from `[table, json]` to `[table, json, csv, yaml, jsonl]`, matching
+  the existing `apcli list` / `apcli exec` choice set. `markdown` and `skill`
+  are deliberately excluded from these subcommands — their payloads are
+  health / strategy results, not `ScannedModule` data. Issue
+  [#20](https://github.com/aiperceivable/apcore-cli/issues/20).
+- **Dependency bump**: requires `apcore >= 0.21.0` (was `>= 0.19.0`) and the
+  optional `[toolkit]` extra now requires `apcore-toolkit >= 0.6` (was `>= 0.5`).
+  Aligns with upstream `apcore 0.21.0` (Module.preview / PreflightResult.predicted_changes,
+  ephemeral.* namespace pilot) and `apcore-toolkit 0.6.0` (surface-aware formatters).
+  No CLI-visible behavioural breaks — apcore 0.20→0.21 deprecations
+  (`TaskStore.put`/`save`, `TaskStatus.RETRYING`, `CircuitOpenError`) keep
+  legacy aliases for one minor release; the cli does not call those surfaces directly.
+- **D1-002 — `CliModuleNotFoundError` renamed to `ModuleNotFoundError`**
+  for cross-language port-ability with TS / Rust `ModuleNotFoundError`.
+  The class intentionally shadows `builtins.ModuleNotFoundError` inside
+  the `apcore_cli` namespace. A deprecation alias
+  `CliModuleNotFoundError = ModuleNotFoundError` is kept for backwards
+  compatibility and will be removed in v0.10.0. Reverses the D2-001
+  rename which predated the cross-SDK parity policy.
+- **Issue #19 — drop "apcore" branding from embedded-mode `--help`**:
+  `create_cli()` now resolves the top-level CLI description from the new
+  `description=` parameter (defaults to `f"{prog_name} CLI"`), the `apcli`
+  subgroup advertises itself as `Built-in commands` rather than
+  `apcore-cli built-in commands`, and the `--verbose` option / footer drop
+  the trailing `apcore` from `(including built-in apcore options)`. Standalone
+  bin entry (`apcore_cli/__main__.py:main()`) passes
+  `description="<prog> — execute apcore modules from the command line"`
+  explicitly so the standalone surface is unchanged.
+
+### Added
+
+- **`--format markdown` and `--format skill`** for `apcli list` and `apcli describe`
+  (issue [#20](https://github.com/aiperceivable/apcore-cli/issues/20)). Both
+  delegate to `apcore_toolkit.format_module(s)` (≥0.6) so the output is
+  byte-identical to the same toolkit call in the TypeScript and Rust SDKs.
+  `--format skill` produces vendor-neutral SKILL.md content directly loadable
+  by Claude Code (`.claude/skills/<id>/SKILL.md`) and Gemini CLI
+  (`.gemini/skills/<id>/SKILL.md`):
+
+  ```bash
+  apcli describe users.create --format skill > .claude/skills/users.create/SKILL.md
+  ```
+
+  A new internal adapter `_descriptor_to_scanned()` maps `ModuleDescriptor`
+  (apcore registry) to `ScannedModule` (apcore-toolkit). A `ClickException` with
+  a clear install hint is raised if the optional `[toolkit]` extra is missing.
+- **Issue #18 — host-app `--version` opt-in**: new `version: str | None = None`
+  parameter on `create_cli()`. When supplied, registers `-V/--version` with
+  the host's version string. **When omitted, the `--version` flag is no
+  longer registered** — embedded CLIs that do not opt in stop leaking the
+  SDK's own version through `-V/--version`. The standalone bin entry
+  passes `version=apcore_cli.__version__` explicitly so the
+  `apcore-cli` binary's behaviour is preserved.
+- **Issue #19 — `description: str | None = None`** on `create_cli()`.
+- **Issue #17 — `system.usage` aggregator + `list --sort calls|errors|latency`**:
+  new module `apcore_cli.system_usage` reads `~/.apcore-cli/audit.jsonl`,
+  filters by period (default 24h), and returns per-module aggregates
+  (`calls`, `errors`, `avg latency_ms`). `list --sort {calls,errors,latency}`
+  now consults the aggregator instead of falling back to id-sort with a
+  buried `logger.warning`. When the audit log has no entries in the period
+  window the discovery layer prints a user-visible note to stderr
+  (`note: no usage data available for --sort <field>; sorted by id. ...`)
+  and falls back to id-sort. Module-protocol registration of
+  `system.usage.summary` / `system.usage.module` as registry-callable
+  built-ins is tracked as a follow-up — today the readers are invoked
+  directly by the discovery layer.
+- New file: `apcore_cli/system_usage.py`.
+
+---
+
 ## [0.7.0] - 2026-04-23
 
 ### Changed

{apcore_cli-0.7.0 → apcore_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apcore-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: Terminal adapter for apcore — execute AI-Perceivable modules from the command line
 Project-URL: Homepage, https://aiperceivable.com
 Project-URL: Repository, https://github.com/aiperceivable/apcore-cli-python
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: apcore>=0.19.0
+Requires-Dist: apcore>=0.21.0
 Requires-Dist: click>=8.1
 Requires-Dist: cryptography>=41.0
 Requires-Dist: jsonschema>=4.20
@@ -37,7 +37,7 @@ Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
 Provides-Extra: toolkit
-Requires-Dist: apcore-toolkit>=0.5; extra == 'toolkit'
+Requires-Dist: apcore-toolkit>=0.6; extra == 'toolkit'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -50,7 +50,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)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
-[![Tests](https://img.shields.io/badge/tests-394%2B%20passed-brightgreen.svg)]()
+[![Tests](https://github.com/aiperceivable/apcore-cli-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aiperceivable/apcore-cli-python/actions/workflows/ci.yml)
 
 | | |
 |---|---|
@@ -90,7 +90,11 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pip install apcore-cli
 ```
 
-Requires Python 3.11+ and `apcore >= 0.17.1`.
+Requires Python 3.11+ and `apcore >= 0.21.0`. The optional `toolkit` extra requires `apcore-toolkit >= 0.6`:
+
+```bash
+pip install "apcore-cli[toolkit]"
+```
 
 ## Quick Start
 
@@ -159,13 +163,22 @@ cli = create_cli(registry=registry, executor=executor, prog_name="myapp")
 
 #### Python API
 
-The `apcore_cli` package exposes three public symbols:
+The `apcore_cli` package re-exports the following public surface (see [`src/apcore_cli/__init__.py`](src/apcore_cli/__init__.py) for the canonical `__all__`):
 
 | Export | Description |
 |--------|-------------|
 | `__version__` | Package version string |
-| `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. See the [`create_cli` reference](https://github.com/aiperceivable/apcore-cli) in the docs site for the full 8-parameter signature (`extensions_dir`, `prog_name`, `commands_dir`, `binding_path`, `registry`, `executor`, `extra_commands`, `expose`). |
+| `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. See the [`create_cli` reference](https://github.com/aiperceivable/apcore-cli) in the docs site for the full 13-parameter signature: `extensions_dir`, `prog_name`, `commands_dir`, `binding_path`, `registry`, `executor`, `extra_commands`, `app`, `expose`, **`apcli`** (FE-13 P0 break), `allowed_prefixes`, `version`, `description`. The `app`, `allowed_prefixes`, `version`, and `description` parameters were added in v0.8.0. |
+| `ApcliGroup`, `ApcliMode`, `RESERVED_GROUP_NAMES` | FE-13 built-in `apcli` group surface (P0 break in v0.8.0). |
 | `ExposureFilter` | Declarative filter controlling which modules are exposed by the CLI (FE-12). |
+| `CliApprovalHandler`, `check_approval` | TTY-aware HITL approval handler / helper (FE-11). |
+| `ConfigResolver` | 4-tier config precedence resolver (CLI flag > env var > config file > default). |
+| `AuditLogger` | Append-only JSON Lines audit logger (`~/.apcore-cli/audit.jsonl`). |
+| `AuthProvider` | API-key authentication provider (keyring-backed). |
+| `ConfigEncryptor` | AES-256-GCM helper for encrypted config blobs. |
+| `Sandbox` | Subprocess sandbox for isolated module execution. |
+| `resolve_refs`, `schema_to_click_options`, `format_exec_result` | Schema/output helper functions. |
+| `ApprovalDeniedError`, `ApprovalTimeoutError`, `AuthenticationError`, `ConfigDecryptionError`, `ModuleExecutionError`, `CliModuleNotFoundError`, `SchemaValidationError` | Typed error classes raised by the SDK (mapped to documented exit codes). |
 
 **Exposure filtering** — restrict which modules are visible at the CLI layer without touching the underlying registry:
 
@@ -195,24 +208,26 @@ cli = create_cli(
 cli = create_cli(registry=registry, executor=executor, extra_commands=[my_custom_click_cmd])
 ```
 
-Or use the `LazyModuleGroup` directly with Click:
+Or build the CLI with a pre-populated registry and executor and full control over the `apcli` built-in group:
 
 ```python
-import click
 from apcore import Registry, Executor
-from apcore_cli.cli import LazyModuleGroup
+from apcore_cli import create_cli, ApcliMode
 
 registry = Registry(extensions_dir="./extensions")
 registry.discover()
 executor = Executor(registry)
 
-@click.group(cls=LazyModuleGroup, registry=registry, executor=executor)
-def cli():
-    pass
-
-cli()
+cli = create_cli(
+    registry=registry,
+    executor=executor,
+    apcli=ApcliMode.ALL,  # or "all" / "none" / {"mode": "include", "include": [...]}
+)
+cli(standalone_mode=True)
 ```
 
+> **Note:** `apcore_cli.cli.LazyModuleGroup` and `GroupedModuleGroup` are advanced internal classes used by `create_cli`. They are subject to change between releases — prefer `create_cli(...)` for stable embedding.
+
 ## Adding Custom Commands
 
 ### Fastest way (30 seconds)
@@ -304,7 +319,7 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 
 ### Built-in Commands
 
-apcore-cli ships with 14 built-in commands, all accessible under the `apcli` subgroup (e.g. `apcore-cli apcli list`). Root-level shims are kept for back-compat and will be removed in v0.8.
+apcore-cli ships with 13 built-in commands, all accessible under the `apcli` subgroup (e.g. `apcore-cli apcli list`). Root-level shims emit a deprecation warning in v0.8.x and are scheduled for removal in v0.9. Use `apcore-cli apcli <subcommand>` to avoid the warning.
 
 **Module invocation**
 
@@ -338,7 +353,8 @@ apcore-cli ships with 14 built-in commands, all accessible under the `apcli` sub
 | Command | Description |
 |---------|-------------|
 | `apcli completion <shell>` | Generate shell completion script (bash/zsh/fish) |
-| `apcli man <command>` | Generate roff man page for a command |
+
+The full-program man page is reachable via the root flag combination `apcore-cli --help --man` (powered by `configure_man_help()`); there is no standalone `apcli man` subcommand.
 
 ### Module Execution Options
 
@@ -401,6 +417,7 @@ apcore-cli uses a 4-tier configuration precedence:
 | `APCORE_CLI_APPROVAL_TIMEOUT` | Approval-gate timeout in seconds (v0.6.0) | `60` |
 | `APCORE_CLI_STRATEGY` | Default execution strategy (v0.6.0) | `standard` |
 | `APCORE_CLI_GROUP_DEPTH` | Depth of automatic command grouping by `.` segments (v0.6.0) | `1` |
+| `APCORE_CLI_APCLI` | FE-13 visibility for the `apcli` built-in group: `all`, `none`, `include`, `exclude`, or `auto` (v0.8.0). Overrides the `apcli:` block in `apcore.yaml`. | `auto` |
 
 ### Config File (`apcore.yaml`)
 
@@ -416,8 +433,32 @@ cli:
   approval_timeout: 60     # v0.6.0
   strategy: standard       # v0.6.0
   group_depth: 1           # v0.6.0
+apcli:                     # v0.8.0 (FE-13)
+  mode: all                # all | none | include | exclude
+  include: []              # used when mode == include
+  exclude: []              # used when mode == exclude
 ```
 
+### `apcli` built-in group visibility (FE-13)
+
+> **P0 breaking change in v0.8.0** — all built-ins were moved under the `apcli` group; the `BUILTIN_COMMANDS` constant has been retired.
+
+The visibility of the `apcli` group is resolved through a 4-tier decision chain:
+
+1. **`create_cli(apcli=...)` kwarg** (highest) — accepts an `ApcliMode` enum, a string (`"all"`, `"none"`, `"include"`, `"exclude"`), or a dict (`{"mode": "include", "include": ["list", "describe"]}`).
+2. **`APCORE_CLI_APCLI` env var** — `all`, `none`, `include`, `exclude`, or `auto`.
+3. **`apcli:` block in `apcore.yaml`** — see the example above.
+4. **Embedded vs. standalone default** (lowest) — standalone `apcore-cli` defaults to `all`; CLIs embedded via `create_cli(app=...)` default to `none` so that host applications opt in explicitly. The `auto` sentinel selects this default and is intended for env/config use only — it is not a user-facing `ApcliMode` value.
+
+The four user-visible modes are:
+
+| Mode | Behavior |
+|------|----------|
+| `all` | All 13 `apcli` subcommands are exposed. |
+| `none` | The `apcli` group is hidden entirely. |
+| `include` | Only the subcommands listed in `include` are exposed. |
+| `exclude` | All subcommands except those listed in `exclude` are exposed. |
+
 ## Features
 
 - **Auto-discovery** -- all modules in the extensions directory are found and exposed as CLI commands
@@ -432,7 +473,7 @@ cli:
 - **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
 - **Shell completions** -- `apcore-cli apcli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
-- **Man pages** -- `apcore-cli apcli man <command>` generates per-command man pages; `--help --man` prints a full-program man page via `configure_man_help()`
+- **Man pages** -- `apcore-cli --help --man` prints a full-program roff man page to stdout, powered by `configure_man_help()` (also exposed for embedded CLIs to opt in)
 - **Documentation URL** -- `set_docs_url()` sets a base URL; per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO links to the full docs site
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
@@ -519,8 +560,8 @@ apcore-cli apcli completion bash >> ~/.bashrc
 apcore-cli apcli completion zsh >> ~/.zshrc
 apcore-cli apcli completion fish > ~/.config/fish/completions/apcore-cli.fish
 
-# Man pages
-apcore-cli apcli man list | man -l -
+# Man pages (full-program roff output)
+apcore-cli --help --man | man -l -
 
 # Run all examples at once
 bash examples/run_examples.sh

{apcore_cli-0.7.0 → apcore_cli-0.8.0}/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)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
-[![Tests](https://img.shields.io/badge/tests-394%2B%20passed-brightgreen.svg)]()
+[![Tests](https://github.com/aiperceivable/apcore-cli-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aiperceivable/apcore-cli-python/actions/workflows/ci.yml)
 
 | | |
 |---|---|
@@ -48,7 +48,11 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pip install apcore-cli
 ```
 
-Requires Python 3.11+ and `apcore >= 0.17.1`.
+Requires Python 3.11+ and `apcore >= 0.21.0`. The optional `toolkit` extra requires `apcore-toolkit >= 0.6`:
+
+```bash
+pip install "apcore-cli[toolkit]"
+```
 
 ## Quick Start
 
@@ -117,13 +121,22 @@ cli = create_cli(registry=registry, executor=executor, prog_name="myapp")
 
 #### Python API
 
-The `apcore_cli` package exposes three public symbols:
+The `apcore_cli` package re-exports the following public surface (see [`src/apcore_cli/__init__.py`](src/apcore_cli/__init__.py) for the canonical `__all__`):
 
 | Export | Description |
 |--------|-------------|
 | `__version__` | Package version string |
-| `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. See the [`create_cli` reference](https://github.com/aiperceivable/apcore-cli) in the docs site for the full 8-parameter signature (`extensions_dir`, `prog_name`, `commands_dir`, `binding_path`, `registry`, `executor`, `extra_commands`, `expose`). |
+| `create_cli(...)` | Factory that builds a ready-to-invoke `click.Group`. See the [`create_cli` reference](https://github.com/aiperceivable/apcore-cli) in the docs site for the full 13-parameter signature: `extensions_dir`, `prog_name`, `commands_dir`, `binding_path`, `registry`, `executor`, `extra_commands`, `app`, `expose`, **`apcli`** (FE-13 P0 break), `allowed_prefixes`, `version`, `description`. The `app`, `allowed_prefixes`, `version`, and `description` parameters were added in v0.8.0. |
+| `ApcliGroup`, `ApcliMode`, `RESERVED_GROUP_NAMES` | FE-13 built-in `apcli` group surface (P0 break in v0.8.0). |
 | `ExposureFilter` | Declarative filter controlling which modules are exposed by the CLI (FE-12). |
+| `CliApprovalHandler`, `check_approval` | TTY-aware HITL approval handler / helper (FE-11). |
+| `ConfigResolver` | 4-tier config precedence resolver (CLI flag > env var > config file > default). |
+| `AuditLogger` | Append-only JSON Lines audit logger (`~/.apcore-cli/audit.jsonl`). |
+| `AuthProvider` | API-key authentication provider (keyring-backed). |
+| `ConfigEncryptor` | AES-256-GCM helper for encrypted config blobs. |
+| `Sandbox` | Subprocess sandbox for isolated module execution. |
+| `resolve_refs`, `schema_to_click_options`, `format_exec_result` | Schema/output helper functions. |
+| `ApprovalDeniedError`, `ApprovalTimeoutError`, `AuthenticationError`, `ConfigDecryptionError`, `ModuleExecutionError`, `CliModuleNotFoundError`, `SchemaValidationError` | Typed error classes raised by the SDK (mapped to documented exit codes). |
 
 **Exposure filtering** — restrict which modules are visible at the CLI layer without touching the underlying registry:
 
@@ -153,24 +166,26 @@ cli = create_cli(
 cli = create_cli(registry=registry, executor=executor, extra_commands=[my_custom_click_cmd])
 ```
 
-Or use the `LazyModuleGroup` directly with Click:
+Or build the CLI with a pre-populated registry and executor and full control over the `apcli` built-in group:
 
 ```python
-import click
 from apcore import Registry, Executor
-from apcore_cli.cli import LazyModuleGroup
+from apcore_cli import create_cli, ApcliMode
 
 registry = Registry(extensions_dir="./extensions")
 registry.discover()
 executor = Executor(registry)
 
-@click.group(cls=LazyModuleGroup, registry=registry, executor=executor)
-def cli():
-    pass
-
-cli()
+cli = create_cli(
+    registry=registry,
+    executor=executor,
+    apcli=ApcliMode.ALL,  # or "all" / "none" / {"mode": "include", "include": [...]}
+)
+cli(standalone_mode=True)
 ```
 
+> **Note:** `apcore_cli.cli.LazyModuleGroup` and `GroupedModuleGroup` are advanced internal classes used by `create_cli`. They are subject to change between releases — prefer `create_cli(...)` for stable embedding.
+
 ## Adding Custom Commands
 
 ### Fastest way (30 seconds)
@@ -262,7 +277,7 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 
 ### Built-in Commands
 
-apcore-cli ships with 14 built-in commands, all accessible under the `apcli` subgroup (e.g. `apcore-cli apcli list`). Root-level shims are kept for back-compat and will be removed in v0.8.
+apcore-cli ships with 13 built-in commands, all accessible under the `apcli` subgroup (e.g. `apcore-cli apcli list`). Root-level shims emit a deprecation warning in v0.8.x and are scheduled for removal in v0.9. Use `apcore-cli apcli <subcommand>` to avoid the warning.
 
 **Module invocation**
 
@@ -296,7 +311,8 @@ apcore-cli ships with 14 built-in commands, all accessible under the `apcli` sub
 | Command | Description |
 |---------|-------------|
 | `apcli completion <shell>` | Generate shell completion script (bash/zsh/fish) |
-| `apcli man <command>` | Generate roff man page for a command |
+
+The full-program man page is reachable via the root flag combination `apcore-cli --help --man` (powered by `configure_man_help()`); there is no standalone `apcli man` subcommand.
 
 ### Module Execution Options
 
@@ -359,6 +375,7 @@ apcore-cli uses a 4-tier configuration precedence:
 | `APCORE_CLI_APPROVAL_TIMEOUT` | Approval-gate timeout in seconds (v0.6.0) | `60` |
 | `APCORE_CLI_STRATEGY` | Default execution strategy (v0.6.0) | `standard` |
 | `APCORE_CLI_GROUP_DEPTH` | Depth of automatic command grouping by `.` segments (v0.6.0) | `1` |
+| `APCORE_CLI_APCLI` | FE-13 visibility for the `apcli` built-in group: `all`, `none`, `include`, `exclude`, or `auto` (v0.8.0). Overrides the `apcli:` block in `apcore.yaml`. | `auto` |
 
 ### Config File (`apcore.yaml`)
 
@@ -374,8 +391,32 @@ cli:
   approval_timeout: 60     # v0.6.0
   strategy: standard       # v0.6.0
   group_depth: 1           # v0.6.0
+apcli:                     # v0.8.0 (FE-13)
+  mode: all                # all | none | include | exclude
+  include: []              # used when mode == include
+  exclude: []              # used when mode == exclude
 ```
 
+### `apcli` built-in group visibility (FE-13)
+
+> **P0 breaking change in v0.8.0** — all built-ins were moved under the `apcli` group; the `BUILTIN_COMMANDS` constant has been retired.
+
+The visibility of the `apcli` group is resolved through a 4-tier decision chain:
+
+1. **`create_cli(apcli=...)` kwarg** (highest) — accepts an `ApcliMode` enum, a string (`"all"`, `"none"`, `"include"`, `"exclude"`), or a dict (`{"mode": "include", "include": ["list", "describe"]}`).
+2. **`APCORE_CLI_APCLI` env var** — `all`, `none`, `include`, `exclude`, or `auto`.
+3. **`apcli:` block in `apcore.yaml`** — see the example above.
+4. **Embedded vs. standalone default** (lowest) — standalone `apcore-cli` defaults to `all`; CLIs embedded via `create_cli(app=...)` default to `none` so that host applications opt in explicitly. The `auto` sentinel selects this default and is intended for env/config use only — it is not a user-facing `ApcliMode` value.
+
+The four user-visible modes are:
+
+| Mode | Behavior |
+|------|----------|
+| `all` | All 13 `apcli` subcommands are exposed. |
+| `none` | The `apcli` group is hidden entirely. |
+| `include` | Only the subcommands listed in `include` are exposed. |
+| `exclude` | All subcommands except those listed in `exclude` are exposed. |
+
 ## Features
 
 - **Auto-discovery** -- all modules in the extensions directory are found and exposed as CLI commands
@@ -390,7 +431,7 @@ cli:
 - **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
 - **Shell completions** -- `apcore-cli apcli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
-- **Man pages** -- `apcore-cli apcli man <command>` generates per-command man pages; `--help --man` prints a full-program man page via `configure_man_help()`
+- **Man pages** -- `apcore-cli --help --man` prints a full-program roff man page to stdout, powered by `configure_man_help()` (also exposed for embedded CLIs to opt in)
 - **Documentation URL** -- `set_docs_url()` sets a base URL; per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO links to the full docs site
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
@@ -477,8 +518,8 @@ apcore-cli apcli completion bash >> ~/.bashrc
 apcore-cli apcli completion zsh >> ~/.zshrc
 apcore-cli apcli completion fish > ~/.config/fish/completions/apcore-cli.fish
 
-# Man pages
-apcore-cli apcli man list | man -l -
+# Man pages (full-program roff output)
+apcore-cli --help --man | man -l -
 
 # Run all examples at once
 bash examples/run_examples.sh