Enterprise-grade framework overhaul: config, tests, CI, enriched schemas

Addresses every gap between documented patterns and actual example code.
Changes verified by 40 integration tests and Codex GPT-5.4 review.

Tier 1 — Credibility fixes:
- Add 40 integration tests across 4 test files verifying exit code
  contracts (0-4), JSON envelope structure, agent-info manifest accuracy,
  and robustness against malformed config
- Add GitHub Actions CI (macOS + Linux)
- Add --quiet global flag (suppresses human output, JSON always emits)
- Replace all hardcoded strings with env!("CARGO_PKG_NAME") / config
- Fix: TTY parse errors now exit 3 (framework code), not 2 (clap code)
- Fix: agent-info/config path work even with malformed config.toml

Tier 2 — Significant improvements:
- Add config loading via figment (3-tier: defaults → TOML → env vars)
- Add config show/path subcommands
- Enrich agent-info with full argument schemas (types, required, defaults,
  possible values) so agents can construct calls without guessing
- Add "Getting Started: Build Your Own" section to README
- Enforce --style values via clap value_parser to match agent-info

Tier 3 — Polish:
- Add CI status and MSRV badges to README
- Update AGENTS.md with Ctx pattern, lazy config, standard commands
- Update CONTRIBUTING.md with test suite and project structure
- Clean clippy warnings (zero warnings with -D warnings)
- Hidden contract command for deterministic exit-code testing
- Hermetic tests (temp HOME for skill install)

Author: longevityboris

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-and-test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: example
+
+      - name: Build
+        working-directory: example
+        run: cargo build --locked
+
+      - name: Test
+        working-directory: example
+        run: cargo test --locked

.gitignore

@@ -2,5 +2,4 @@ target/
 .claude/
 .agents/
 .cursor/
-.github/
 .windsurf/

AGENTS.md

@@ -14,14 +14,17 @@ Split your CLI into focused modules. Never write a monolithic main.rs.
 src/
   main.rs         # Entry point only: parse, detect format, dispatch, exit
   cli.rs          # Clap derive: Cli struct + Commands enum + Args structs
+  config.rs       # AppConfig + load() via figment (3-tier precedence)
   error.rs        # Error enum with exit_code(), error_code(), suggestion()
-  output.rs       # Format enum + print_success_or() + print_error()
+  output.rs       # Format enum, Ctx struct, print_success_or(), print_error()
   commands/
     mod.rs        # Re-exports
     <command>.rs  # One file per domain command
-    agent_info.rs # Capability manifest (always present)
+    agent_info.rs # Capability manifest with arg schemas (always present)
     skill.rs      # Skill install + status (always present)
+    config.rs     # config show/path (always present)
     update.rs     # Self-update (optional)
+  tests/          # Integration tests verifying contracts
   Cargo.toml
 ```
 
@@ -38,7 +41,7 @@ src/
 
 ## Output Format
 
-Detect automatically:
+Detect automatically. Bundle format + quiet into an output context:
 
 ```rust
 pub enum Format { Json, Human }
@@ -49,8 +52,18 @@ impl Format {
         else { Format::Human }
     }
 }
+
+pub struct Ctx { pub format: Format, pub quiet: bool }
+
+impl Ctx {
+    pub fn new(json_flag: bool, quiet: bool) -> Self {
+        Self { format: Format::detect(json_flag), quiet }
+    }
+}
 ```
 
+Pass `Ctx` to all commands. `--quiet` suppresses human output; JSON always emits.
+
 Success envelope (stdout):
 ```json
 {"version": "1", "status": "success", "data": { ... }}
@@ -107,9 +120,13 @@ fn main() {
             std::process::exit(3);
         }
     };
-    let format = Format::detect(cli.json);
-    if let Err(e) = run(cli, format) {
-        print_error(format, &e);
+    let ctx = Ctx::new(cli.json, cli.quiet);
+    let config = config::load().unwrap_or_else(|e| {
+        print_error(ctx.format, &e);
+        std::process::exit(e.exit_code());
+    });
+    if let Err(e) = run(cli, ctx, &config) {
+        print_error(ctx.format, &e);
         std::process::exit(e.exit_code());
     }
 }
@@ -147,16 +164,18 @@ Every CLI has these built-in commands:
 - `skill install` -- write SKILL.md to `~/.claude/skills/<name>/`, `~/.codex/skills/<name>/`, `~/.gemini/skills/<name>/`
 - `skill status` -- check installation status
 
+Standard:
+- `config show` -- display effective merged config (secrets masked)
+- `config path` -- print config file path
+
 Optional:
 - `update [--check]` -- self-update from GitHub Releases
-- `config show` -- display current config (secrets masked)
-- `config set <key> <value>` -- update config
 
 ## Global Flags
 
 Always at the top-level `Cli` struct:
-- `--json` -- force JSON output even in terminal (required)
-- `--quiet` -- suppress non-essential output (add if your CLI has verbose default output)
+- `--json` -- force JSON output even in terminal (required, always present)
+- `--quiet` -- suppress informational human output; JSON always emits (required, always present)
 
 ## Dependencies
 

CONTRIBUTING.md

@@ -7,15 +7,16 @@ Thanks for your interest in contributing.
 1. Fork the repo and create a branch from `main`.
 2. Make your changes. Keep them focused -- one concern per PR.
 3. If you add a pattern, include it in both the README and the `example/` CLI.
-4. Test that the example builds and all behaviors work:
+4. Run the full test suite:
    ```bash
-   cd example && cargo build --release
-   ./target/release/greeter hello Boris --style pirate
-   ./target/release/greeter hello Boris | jq        # JSON envelope
-   ./target/release/greeter hello "" 2>&1; echo $?  # exit code 3
-   ./target/release/greeter --help > /dev/null; echo $?  # exit code 0
-   ./target/release/greeter agent-info | jq          # valid manifest
+   cd example && cargo test --locked
    ```
+   All integration tests must pass. They verify:
+   - Exit code contracts (0-4)
+   - JSON envelope structure (success + error)
+   - `--help`/`--version` exit 0
+   - `agent-info` manifest matches actual commands
+   - Piped output auto-switches to JSON
 5. Open a pull request with a clear description of what you changed and why.
 
 ## Project structure
@@ -24,18 +25,26 @@ Thanks for your interest in contributing.
 README.md              # Full framework documentation: philosophy, patterns, reusable modules
 AGENTS.md              # Condensed build instructions for AI coding agents
 CONTRIBUTING.md        # This file
+.github/workflows/     # CI: builds and tests on macOS + Linux
 example/
   src/
     main.rs            # Entry point: parse, detect format, dispatch, exit
-    cli.rs             # Clap derive definitions
+    cli.rs             # Clap derive definitions (--json, --quiet, all commands)
+    config.rs          # Config loading via figment (defaults -> TOML -> env vars)
     error.rs           # Error enum with exit_code(), error_code(), suggestion()
-    output.rs          # Format detection + JSON envelope helpers
+    output.rs          # Format detection, Ctx struct, JSON envelope helpers
     commands/
       mod.rs           # Re-exports
       hello.rs         # Domain command example
-      agent_info.rs    # Capability manifest
-      skill.rs         # Skill install + status
-      update.rs        # Self-update
+      agent_info.rs    # Enriched capability manifest with arg schemas
+      config.rs        # config show/path
+      contract.rs      # Hidden deterministic exit-code trigger for tests
+      skill.rs         # Skill install + status (uses CARGO_PKG_NAME)
+      update.rs        # Self-update (repo configurable via config)
+  tests/
+    exit_code_contracts.rs   # All 5 exit codes verified
+    output_contracts.rs      # JSON envelope shape, quiet flag, help wrapping
+    agent_info_contract.rs   # Manifest fields, routable commands, arg schemas
   Cargo.toml
 ```
 
@@ -44,14 +53,15 @@ example/
 - New patterns or refinements to existing ones, backed by real-world agent usage.
 - Bug fixes or improvements to the example CLI.
 - Documentation improvements that make the patterns clearer or more precise.
-- Integration tests that verify framework invariants (help exits 0, piped output is valid JSON, etc.).
+- Additional integration tests verifying framework invariants.
 - Links to additional CLIs built with this architecture.
 
 ## Guidelines
 
 - The example demonstrates the five core patterns plus the entry point, error type, and output helpers. Reusable modules like config loading, secret handling, and HTTP retry are documented as code patterns in the README -- they don't need to be in the example.
 - Keep the example minimal -- it demonstrates patterns, not a real product.
 - Ensure the README, AGENTS.md, and example stay consistent with each other.
+- All new patterns must have corresponding integration tests.
 
 ## Style
 

README.md

@@ -12,15 +12,17 @@
 
 <br />
 
+[![CI](https://github.com/199-biotechnologies/agent-cli-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/199-biotechnologies/agent-cli-framework/actions/workflows/ci.yml)
 [![Rust](https://img.shields.io/badge/Rust-000000?style=for-the-badge&logo=rust&logoColor=white)](https://www.rust-lang.org/)
+[![MSRV 1.85+](https://img.shields.io/badge/MSRV-1.85%2B-orange?style=for-the-badge)](https://www.rust-lang.org/)
 [![MIT License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen?style=for-the-badge)](CONTRIBUTING.md)
 
 ---
 
 Five patterns turn any Rust CLI into a tool AI agents can pick up and use without documentation, MCP servers, or skill files. The binary describes itself, returns structured output, and uses semantic exit codes. Your CLI becomes the tool, the documentation, and the API -- all in one binary.
 
-[Philosophy](#philosophy) | [Why This Exists](#why-this-exists) | [Patterns](#patterns) | [Reusable Modules](#reusable-modules) | [Example](#example) | [Invariants](#invariants)
+[Philosophy](#philosophy) | [Why This Exists](#why-this-exists) | [Patterns](#patterns) | [Reusable Modules](#reusable-modules) | [Getting Started](#getting-started-build-your-own) | [Example](#example) | [Invariants](#invariants)
 
 </div>
 
@@ -619,6 +621,67 @@ pub fn should_retry(err: &reqwest::Error) -> bool {
 
 ---
 
+## Getting Started: Build Your Own
+
+**1. Copy the scaffold:**
+
+```bash
+cp -r example/ my-cli/
+cd my-cli/
+```
+
+**2. Rename the binary** in `Cargo.toml`:
+
+```toml
+[package]
+name = "my-cli"                      # Your binary name
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+```
+
+Update the `[[bin]]` section and the `#[command(name = "...")]` in `cli.rs`.
+
+**3. Replace the `hello` command** with your domain logic. Keep the same structure:
+
+```
+src/
+  main.rs           # Entry point (barely changes between CLIs)
+  cli.rs            # clap derive definitions
+  config.rs         # 3-tier config loading
+  error.rs          # AppError with exit_code(), error_code(), suggestion()
+  output.rs         # Format detection + envelope helpers
+  commands/
+    mod.rs
+    agent_info.rs   # Update: list YOUR commands
+    your_command.rs  # Your domain logic
+    skill.rs        # Skill content auto-derived from CARGO_PKG_NAME
+    config.rs       # config show/path (works out of the box)
+    update.rs       # Self-update (just change repo owner/name in config)
+```
+
+**4. Update `agent-info`** to list your actual commands with argument schemas. This is the contract agents bootstrap from.
+
+**5. Write tests and run them:**
+
+```bash
+cargo test                           # All integration tests
+cargo run -- agent-info              # Verify manifest
+cargo run -- config show             # Verify config loading
+echo '{}' | cargo run -- hello Test  # Verify JSON envelope in pipe
+```
+
+**6. Ship it:**
+
+```bash
+cargo build --release                # Single binary, sub-10ms cold start
+./target/release/my-cli skill install  # Deploy to Claude/Codex/Gemini
+```
+
+The framework conventions (`env!("CARGO_PKG_NAME")`, config loading, skill install) adapt automatically when you rename the package. No find-and-replace needed.
+
+---
+
 ## Example
 
 The `example/` directory contains a modular `greeter` CLI demonstrating the five core patterns (agent-info, JSON envelope, semantic exit codes, skill self-install, self-update) and the reusable entry point, error type, and output helpers. Config loading, secret handling, XDG paths, and HTTP retry are documented as code patterns in the Reusable Modules section above -- copy them into your CLI when you need them.