docs: add AGENTS.md and CLAUDE.md SDK documentation

[ignaciosantise]

Summary

Add comprehensive SDK documentation files to help agents and developers understand the AppKit React Native architecture and development guidelines.

• AGENTS.md: Complete SDK overview, architecture patterns, UI system details, and agent guidance
• CLAUDE.md: Simple reference link to AGENTS.md

This documentation covers the monorepo structure, controller/adapter/connector patterns, theming system, UI components, and code quality requirements including formatting, linting, testing, and dependency policies.

🤖 Generated with Claude Code

---

Note

Adds SDK documentation for reviewers and agents.

• AGENTS.md: Comprehensive overview of AppKit React Native, including monorepo structure, controller/adapter/connector patterns, UI system (components, theming, animations, views/router), and agent guidance (code quality, platform compatibility, dependency policy, key abstractions, important files, dev commands, commit convention)
• CLAUDE.md: Pointer file referencing AGENTS.md

^{Written by Cursor Bugbot for commit 36db6f7. This will update automatically on new commits. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 36db6f7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[claude]

Claude finished @ignaciosantise's task —— View job

---

PR Review Complete ✅

• Read and analyze AGENTS.md
• Read and analyze CLAUDE.md
• Review documentation quality and accuracy
• Verify alignment with project structure
• Provide final review feedback

---

Review Findings

Documentation Accuracy Issues

AGENTS.md:75 - Component count inaccuracy:

├── components/               # 13 base primitives (Card, Icon, Text, Image, Modal, etc.)

• Issue: Claims 13 base components, but only 11 exist in packages/ui/src/components/
• Fix: Change to # 11 base primitives

AGENTS.md:79 - Composite count accurate (42 ✓)

AGENTS.md:164 - View count inaccuracy:

**RouterController** manages navigation between 23 views:

• Issue: Claims 23 views but RouterController.ts defines 28 view types (lines 11-40) and packages/appkit/src/views/ contains 29 view directories
• Actual view types: Account, AccountDefault, AllWallets, Connect, ConnectSocials, ConnectingExternal, ConnectingSocial, GetWallet, Networks, OnRamp, OnRampCheckout, OnRampLoading, OnRampSettings, OnRampTransaction, SIWXSignMessage, Swap, SwapPreview, SwitchNetwork, Transactions, UnsupportedChain, UpgradeEmailWallet, WalletCompatibleNetworks, WalletConnect, WalletReceive, WalletSend, WalletSendPreview, WalletSendSelectToken, WhatIsANetwork, WhatIsAWallet (28 total)
• Fix: Change to "28 views" and update the list to include missing views: OnRampLoading, OnRampTransaction, SIWXSignMessage, UpgradeEmailWallet, WalletCompatibleNetworks

AGENTS.md:90 - Partials count inaccuracy:

└── partials/                 # 24 AppKit-specific composites (Header, Snackbar, QrCode, etc.)

• Issue: Claims 24 partials, but only 19 exist in packages/appkit/src/partials/
• Fix: Change to # 19 AppKit-specific composites

AGENTS.md:265 - Line count accuracy:

packages/appkit/src/AppKit.ts          # Main SDK class (~900 LOC)

• Verified: Actual line count is 913 lines, so "~900 LOC" is accurate ✓

AGENTS.md:97 - Missing base component:

• The documentation lists icons like "wui-icon" but doesn't mention wui-visual which exists as a base component

AGENTS.md:119-146 - Theme system verification needed:

• Claims 62 theme color keys but this wasn't verified against actual theme implementation
• Typography variants claim "24 variants" but this wasn't verified

Missing View Types in Documentation

The following views exist in RouterController but aren't mentioned in the documentation list (AGENTS.md:165-171):

• OnRampLoading
• OnRampTransaction
• SIWXSignMessage
• UpgradeEmailWallet
• WalletCompatibleNetworks
• GetWallet
• AllWallets
• ConnectingSocial

CLAUDE.md Assessment

CLAUDE.md:1 - Minimal content:

AGENTS.md

• Issue: This file only contains a single word reference to AGENTS.md
• Concern: Based on the PR description stating "CLAUDE.md: Simple reference link to AGENTS.md", this appears intentional but is extremely minimal
• Suggestion: Consider adding a brief explanation like:

  # AppKit React Native - Agent Instructions
  
  See [AGENTS.md](./AGENTS.md) for comprehensive SDK documentation and development guidelines.

Positive Observations

✅ Comprehensive SDK overview with clear architectural patterns
✅ Well-organized monorepo structure documentation
✅ Detailed UI system breakdown with component hierarchy
✅ Helpful theming and animation guidance
✅ Clear agent guidance with quality requirements
✅ Appropriate dependency policy emphasis
✅ No security concerns in documentation

Changeset Assessment

The changeset-bot correctly flagged that no changeset was added. For documentation-only changes, a changeset is typically not required unless your project's policy differs. However, if you want these docs to be mentioned in release notes, consider adding a patch-level changeset with:

yarn changeset add

Select "patch" for the relevant packages and describe it as documentation improvements.

---

Recommendation: Fix the numerical inaccuracies before merging to ensure agents have accurate information about the codebase structure.

---

[Copilot]

Pull request overview

Adds agent/developer-facing SDK documentation intended to explain the AppKit React Native monorepo architecture, UI system, and development guidelines.

Changes:

• Added AGENTS.md with SDK overview, patterns, UI/theming details, and agent guidance.
• Added CLAUDE.md intended to point readers to AGENTS.md.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
CLAUDE.md	Adds a pointer to the main agent/developer documentation.
AGENTS.md	Introduces comprehensive documentation about repo structure, architecture patterns, UI/theming system, and workflow requirements.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ignaciosantise]

Thanks for the thorough review! I've addressed all the feedback:

1. Base components count: Fixed to 11 ✓
2. RouterController views: Now references source file instead of hardcoded list ✓
3. Animation patterns: Clarified native driver vs JS-driven animations ✓
4. Typography variants: Fixed to 23 variants with 400/500/600/700 weights ✓
5. React Native version: Updated to 0.72+ (tested with 0.76+) ✓
6. CLAUDE.md link: Keeping as plain text per project maintainer's request

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud