docs: add CLAUDE.md — this repo had no agent entry point at all

[DealAppSeo]

Description

A find across this repository's whole tree for CLAUDE.md / AGENTS.md / LESSONS.md returned nothing [MEASURED 2026-09-08]. The four sibling repositories each carry one. So an agent starting work here saw no operating rules, no hard stops, and no indication that either existed elsewhere.

That is the worst shape of the problem, because nothing announces it. A missing file raises no warning, fails no check, and returns no 404 — it just produces an agent proceeding confidently with less context than it believes it has.

This adds one file. It carries only what was measured here or is already canonical on another surface.

The hard stop was recorded at the wrong paths

repid-engine/CLAUDE.md lists Marco De Rossi's protected files as bare root-level names — ERC8004SPEC.md, contracts/, test/, abis/. None of the four exist at this repository's root. All live under packages/contracts/.

Verified in this branch:

VERIFIED exists: packages/contracts/ERC8004SPEC.md
VERIFIED exists: packages/contracts/contracts
VERIFIED exists: packages/contracts/test
VERIFIED exists: packages/contracts/abis
root lacks ERC8004SPEC.md / contracts / test / abis

An agent that checked the documented path, found nothing, and concluded the hard stop had gone stale would have read a live prohibition as a dead one — on the one set of files that must not be touched. The wrong line is corrected in repid-engine in the same change (DealAppSeo/repid-engine#686).

What else is in the file

• The per-surface read-first table, so the pointer exists on the surface an agent actually lands on rather than only inside another repo's LESSONS.md.
• Public-repo discipline — Apache 2.0, published as @hyperdag/protocol. State findings, not inventories; a secret in git history stays public after deletion from HEAD.
• Sean's six execution rules and three-outcome reporting (VERIFIED / NOT CHECKED / FAILED).
• The operator environment (Windows PowerShell 5.1, Node v22.17.0), so command blocks handed over from here are runnable as written rather than bash that errors on &&.

No addresses or keys are copied into the file; README.md stays the source for those.

Fixes # (no issue — found while auditing entry points across all five surfaces)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

How Has This Been Tested?

Documentation only — one new file, no code paths touched, nothing imported or built differently.

Every factual claim in the file was verified against the tree on this branch rather than carried over from another document:

• The absence that motivates the file: find . -iname 'CLAUDE.md' -o -iname 'AGENTS.md' -o -iname 'LESSONS.md' → no results.
• All four hard-stop paths asserted present under packages/contracts/, and all four asserted absent from the root (output above).
• Package layout (packages/{circuits,contracts,defaults}) and the Apache 2.0 / npm publication status read from README.md and package.json.

The sibling entry points named in the read-first table were each read to confirm the file this table sends an agent to is the one that actually exists there — including that trustshell/CLAUDE.md is a one-line @AGENTS.md include, which is why the table names AGENTS.md for that surface.

NOT CHECKED: whether this repository runs a Strix review or other required checks — that will be visible on this PR itself, and the verdict should land before merge.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

🤖 Generated with Claude Code

https://claude.ai/code/session_01F3yrSVaGDLirLw4itQJ5wK

---

Generated by Claude Code

[strix-security]

Strix Security Review

No security issues found.

_{Updated for 254d7c3.}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}