docs(cpex): add intro + links to the crate root, document full API on docs.rs

- lib.rs: lead the crate docs with what CPEX is (policy enforcement runtime
  for AI agents, the reference-monitor model) instead of opening on 'host
  facade', and link the guide site and repo. Move the facade explanation under
  a 'This crate' heading.
- Cargo.toml: add [package.metadata.docs.rs] all-features = true. The default
  build is engine-only, so docs.rs was omitting the builtins re-exports /
  install_builtins and the cpex-builtins intra-doc link did not resolve.

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

crates/cpex/Cargo.toml

@@ -30,6 +30,13 @@ keywords.workspace = true
 categories.workspace = true
 rust-version.workspace = true
 
+# Build docs.rs with every extension enabled. The default build is engine-only
+# (`default = []`), which omits cpex-builtins entirely — so without this the
+# builtins re-exports and `install_builtins` are absent and the intra-doc link
+# to `cpex-builtins` does not resolve on docs.rs.
+[package.metadata.docs.rs]
+all-features = true
+
 [features]
 # Engine only by default: no builtin plugins are compiled in. Opt into the
 # bundled extensions with `builtins` (the common in-process set), `full`

crates/cpex/src/lib.rs

@@ -3,15 +3,30 @@
 // SPDX-License-Identifier: Apache-2.0
 // Authors: Fred Araujo
 
-//! CPEX host facade.
+//! **CPEX is a policy enforcement runtime for AI agents.**
 //!
-//! A single dependency that re-exports the CPEX host runtime, so hosts
-//! depend on this crate instead of pinning `apl-cmf`, `apl-cpex`, and
-//! `cpex-core` one by one.
+//! It is a deterministic reference monitor between an agent and every
+//! capability it invokes: tools, prompts, resources, inference providers, and
+//! A2A methods. Each operation runs through a policy-defined pipeline that can
+//! resolve identity, make an authorization decision (delegated to an engine
+//! like Cedar or CEL), exchange and reduce credentials before a downstream
+//! call, redact inputs and outputs, track information flow across calls, and
+//! audit. You write that policy declaratively in APL (Authorization Policy
+//! Language); CPEX evaluates and enforces it at the boundary, against state
+//! the model cannot observe or forge.
 //!
-//! By default this is the **engine only** — no builtin plugins are compiled
-//! in. The bundled extension set lives in [`cpex-builtins`](cpex_builtins)
-//! and is pulled in only when a builtins feature is enabled.
+//! - Guide and concepts: <https://contextforge-org.github.io/cpex/>
+//! - Source and issues: <https://github.com/contextforge-org/cpex>
+//!
+//! # This crate
+//!
+//! `cpex` is the **host facade**: one dependency that re-exports the CPEX
+//! runtime (`cpex-core`, `apl-core`, `apl-cmf`, `apl-cpex`), so a host depends
+//! on this crate instead of pinning each of them separately.
+//!
+//! By default it is the **engine only**: no builtin plugins are compiled in.
+//! The bundled extension set lives in [`cpex-builtins`](cpex_builtins) and is
+//! pulled in only when a builtins feature is enabled.
 //!
 //! # Usage
 //!