docs: name the smart wallet as a tenant, not a protocol citizen

[nandal]

Closes the documentation gap that produced the SDK-vs-app-layer confusion in #39.

The problem

protocol-family.md opens with "Nothing else lives at the protocol layer." Meanwhile contracts/v3/wallet/ sits in the contracts tree holding a smart wallet and its factory.

Both statements are true — the wallet genuinely isn't protocol — but nothing said so. The only explanation lived in a source-file header comment: it's a minimal fork of Coinbase's CoinbaseSmartWallet.sol, kept in the monorepo for v1 development, scheduled to split out to a public base-passkey-wallet repo at mainnet.

A reader who finds the directory before finding that comment has every reason to assume the wallet is protocol and to build on it accordingly. That is what happened in #39, where the request was to put client-side wallet derivation into @bytesbrains/maktub-sdk.

What this adds

protocol-family.md §6.1 — "The smart wallet is not a citizen", placed in the existing What is NOT in the protocol section and written in the same disclosure-blockquote style §3 already uses for the ExecutorRewards admin-roles caveat. It covers:

• The wallet is neither citizen (§2) nor substrate (§3), and its absence from both tables is deliberate
• Why it is in this repo anyway — fork provenance, build convenience, and the documented move date
• Why its addresses ship in the deployment carrier without that implying protocol status: clients derive counterfactual accounts from them and would otherwise hardcode the pair outside the drift check
• The consequence for contributors — client-side derivation against these contracts is app-layer and does not belong in the protocol SDK
• The one property it does share: immutability (UUPS stripped, single owner, no v1 recovery path)

A pointer in §3 noting the substrate table is exhaustive and the wallet is not on it.

contracts/CLAUDE.md gets the same note at the directory table. That file listed wallet/ with no explanation directly above "No other citizens at the protocol layer," and it is what gets read when working in contracts/.

Verified, not asserted

The doc claims the separation is structural in both directions. Both were checked against the tree:

Claim	Result
Nothing in core/ references the wallet	0 hits
The wallet references no Maktub contract	0 hits
No UUPS / upgradeability	none present
No addOwner / recovery in v1	0 hits

The wallet's external surface is entirely generic: initialize, execute, executeBatch, entryPoint, owner, isValidSignature. The only Maktub-specific thing about it is its name.

Scope

Documentation only — no contract, test, or behavior change. Nothing here weakens or restates an invariant; §6.1 explains why an existing claim is true rather than qualifying it.

Refs #39

🤖 Generated with Claude Code

[wrokin]

🛡️ wrokin security hunter

No vulnerabilities were proven in this pull request — the hunter found nothing it could exploit and prove by execution.

Advisory only — this check never blocks your PR.

[wrokin]

🤖 wrokin code review

Documentation clarifies wallet contracts as non-protocol tenants, consistent with existing repo conventions and issue #39.

No bugs, security, or correctness issues identified in this documentation-only diff.

🌾 wrokin contribution signal

• The linked issue [medium] SDK packaging blocks browser consumers: CJS-only barrel pulls Veil + WASM into every import #39 requests concrete SDK changes (ESM build, exports map, and four wallet-client logic pieces) — this diff adds only documentation, leaving every requirement from that issue unaddressed.
• The new note in contracts/CLAUDE.md instructs contributors not to build SDK surface over the wallet and cites issue [medium] SDK packaging blocks browser consumers: CJS-only barrel pulls Veil + WASM into every import #39 as the rationale, creating a circular reference where the PR points to the issue that asks for that very surface; this may confuse rather than clarify the relationship.

_{Advisory — signals worth a closer look, not a verdict or a score.}

_{Model: deepseek/deepseek-v4-pro · your key, your model (BYOK) · Context: #39}

[wrokin]

🤖 wrokin security audit

No security-relevant findings in this diff. The changes are documentation-only clarifications that reinforce existing security boundaries (wallet contracts are not part of the protocol, no protocol dependency, and immutability expectations). There is no injection, authz, secrets exposure, unsafe deserialization, or similar vulnerability introduced or exacerbated by these textual edits.

_{Model: deepseek/deepseek-v4-pro · your key, your model (BYOK) · Context: #39}