docs: SDK ergonomics for Praefectus

[undivisible]

Lead the README with a one-line pitch and a runnable Quick Start before the protocol essay, add AGENTS.md for layout and non-invented APIs, and ship a credential-free library example.

Changes

• README: one-line pitch + ## Quick Start (cargo build / cargo test, capabilities / surfaces / status, cargo run --example capabilities) before the trust-model and protocol essay. Existing CLI/library/protocol text is unchanged aside from the new top matter and a Development example command. The stale 0.7.0 version label is dropped so the crate version in Cargo.toml stays the source of truth.
• AGENTS.md: layout, build/test gates, CLI vs library paths, and what not to invent (no fake execute CLI, no secrets, no remote CDP, no host approval ledgers).
• examples/: capabilities.rs constructs Engine with NativeExecutor and DenyAuthority, prints capabilities, and reads status for a missing operation ID. examples/README.md follows the equilibrium name / run / Demonstrates layout.
• Cargo.toml: [[example]] plus /examples/** in include.

No runtime behavior changes.

Verification

Ran on this branch:

• cargo fmt --all -- --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo clippy --all-targets -- -D warnings
• cargo check --all-targets --all-features
• cargo test --all-features (one pre-existing env failure, see below)
• cargo run --example capabilities → platform=linux backend=praefectus-linux status=none
• cargo run -- capabilities → ok: true
• cargo run -- surfaces → observation_error / exit 3 (no AT-SPI desktop)
• cargo run -- status --ledger ./operations.jsonl example-missing-operation → {"data":null,"ok":true}
• cargo package --list includes examples/capabilities.rs and examples/README.md

native_executor_routes_coordinate_effects fails on this agent VM because DISPLAY=:1 is set, so the Linux early-return does not apply, move is advertised, and global input is refused as NoEffect. That assertion is unchanged on main and is outside this docs-only PR. GitHub Actions Ubuntu has no DISPLAY/WAYLAND_DISPLAY and skips that path.

  

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b0ca9f84-a95d-4861-aeab-34138048254d)