@agenticprimitives/devkit 0.0.0-alpha.6 → 0.0.0-alpha.8

package/README.md

@@ -1,5 +1,7 @@
 # @agenticprimitives/devkit
 
+> Part of **[Agentic Primitives](https://agenticprimitives.dev)** — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. [Developer kit](https://github.com/agentictrustlabs/agentic-primitives) · [All packages](https://agenticprimitives.dev/developers)
+
 The Developer Kit core — `ap`, the CLI that is the packages' own front door (spec 398 §10, spec 399 §3, ADR-0063).
 
 ```
@@ -75,6 +77,35 @@ It is the **third** MCP — not the runtime's private MCP behind admission (ADR-
 and its `ap://developer-mcp/doctrine` resource says so first: no signing key, no vault, no authority, no production
 effect (spec 398 §10.4, T23). Claude Code: `claude mcp add ap-dev -- npx ap mcp --root .`
 
+## `ap generate client|cli|parity` — the fourth and fifth surfaces of one contract (398 §7.2)
+
+```
+ap generate client --registry https://<skills-registry> --definition agentic-trust/person-steward --only web.search,person.memory.remember --out src/lib/agent-client.ts
+ap generate cli    --registry … --definition agentic-trust/org-steward --only treasury.payment.execute
+ap generate parity --registry … --definition agentic-trust/org-steward --json
+```
+
+Projected FROM the compiled definition (the registry's, or `--file <definition.json>`) by `@agenticprimitives/harness`'s
+pure `generateCapabilityClient` / `cliArgumentSchema` / `generateParityCases` — the kit dispatches to the consumer's
+install (absent ⇒ `E_MODULE_ABSENT`). The client's every operation posts an intent to the app's `/harness/run` boundary
+through an injected port and carries no authority; the parity cases are the positive pair (screen intent vs Ask
+sentence → the same normalized plan digest) and the negative pair (a forged `surface`, a changed party after approval).
+Regenerate after `ap upgrade` moves a pinned definition.
+
+## `ap eval` — cases as data against a live Home (398 §10 / P1.3)
+
+```
+ap eval evals/faithnet.eval.json --home https://www.faithnet.me --persona alice --report live-gates-reports/eval-faithnet-latest.json
+ap eval --from-runs --home https://www.faithnet.me --persona alice --out evals/from-runs.eval.json
+```
+
+A case is `{ id, incident, persona | (the --session bearer), addressee?, message, plan?, truth?, checks[] }`; a check is
+one of the deterministic judges by name (`answered`, `replyKindIs`, `neverClaims`, `claimsRequire`, `falseEmptiness`,
+`emptinessCarriesReason`, `evidenceFromTool`, `evidenceCountAgrees`, `noPlaceholderLeaks`, `textIncludes`,
+`textExcludes`, `evidenceNoneFrom`). An act's correct outcome in a case is `authority_required` — the twin, as a test;
+an eval never signs. An unrunnable case is a FAILING case. `--from-runs` turns an agent's live run records into case
+skeletons to edit. Exit 1 on any failing case.
+
 ## What it will not do
 
 Hold a key, read a vault, mint authority, invoke a production effect. A doctor finding is a review checkpoint;