@agenticprimitives/devkit 0.0.0-alpha.3 → 0.0.0-alpha.31

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).
 
 ```
@@ -56,6 +58,54 @@ a consumer uses the copy bundled in the package.
 `packages` is the coherent set `ap upgrade` maintains; `rules` the source digests; `doctor` the product's rule
 config (each section replaces the reference section whole).
 
+## Pinned definitions — `ap upgrade` stops for review (398 §10.3)
+
+`ap upgrade --pin-definitions <registry> agentic-trust/org-steward,agentic-trust/person-steward` records, in
+`agentic.lock.json#definitions`, each archetype definition's digest and the **authority shape** of every tool (risk,
+action, requirement type, resource and authority args, approval policy, effects, idempotency). Every later `ap upgrade`
+reads the registry first: a wording change is a version bump; a change to any of those fields stops the upgrade with the
+change named per tool (`treasury.payment.execute: authorityArg payer → org`), and `--accept-definitions` re-pins once a
+reviewer has read it. The pin is a reviewer's memory, never a verifier's input.
+
+## The Developer MCP (`ap mcp`)
+
+A coding agent's host spawns `ap mcp` (stdio JSON-RPC) and gets a **read-only** server: `packages_list`,
+`package_exports` (the names each entry's `.d.ts` declares), `ontology_term` (T-box IRI, label, comment — what a term
+means and what it is not), `contract_deployments` (addresses per chain), `recipes` (the agent rules and each
+package's spec), `doctor` (the same report, redacted). Everything is answered from the packages installed beside it.
+It is the **third** MCP — not the runtime's private MCP behind admission (ADR-0057), not the Home MCP (spec 397) —
+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;