Make repo structure compliant

.claude/skills/code-quality/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: code-quality
+description: Review or improve code, documentation and configuration against this repository's conventions and design constraints. Use for code-quality, style or consistency reviews.
+---
+
+# Code quality
+
+Run repository commands from the repository root. For untrusted PRs, run builds and tests
+only in an isolated sandbox without credentials; otherwise rely on maintainer-approved CI.
+Builds execute the repository's Rust macro plugin.
+
+1. Review the requested scope. Otherwise, compare against the PR base, including staged,
+   unstaged and untracked changes. For stacked PRs, use the immediate parent branch.
+   Without a PR, identify and state the base from local context. Exclude generated files only
+   as documented by the repository. If nothing is in scope, say so.
+2. Read the relevant [guidelines](../../../GUIDELINES.md),
+   [architecture](../../../ARCHITECTURE.md) and [contribution guide](../../../CONTRIBUTING.md).
+   Use the setup and verification commands in the contribution guide.
+3. Report findings with file, line and proposed correction. Cite the relevant convention or
+   evidence of a defect. Identify documentation gaps rather than inventing rules.
+4. For fix requests, apply supported corrections and run the relevant checks. For review-only
+   requests, report findings without editing. State checks that could not run and why.

.coderabbit.yaml

@@ -0,0 +1,6 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+knowledge_base:
+  code_guidelines:
+    filePatterns:
+      - "GUIDELINES.md"
+      - "ARCHITECTURE.md"

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @ericnordelo @immrsd @bidzyyys

.github/copilot-instructions.md

@@ -0,0 +1,14 @@
+# GitHub Copilot instructions
+
+Read and follow [AGENTS.md](../AGENTS.md), [GUIDELINES.md](../GUIDELINES.md) and
+[ARCHITECTURE.md](../ARCHITECTURE.md). Use the setup and verification commands linked from
+`AGENTS.md`.
+
+## Critical conventions
+
+- Prefer numeric literals without type suffixes when the compiler can infer the type.
+- Prefix component storage members with the component name (for example `ERC20_balances`).
+  Preserve deployed field names and types; assess storage compatibility before changing them.
+
+For reviews, follow the [code-quality procedure](../.claude/skills/code-quality/SKILL.md).
+Do not present undocumented preferences as repository rules.

.github/workflows/test.yml

@@ -38,11 +38,10 @@ jobs:
         run: curl -L https://raw.githubusercontent.com/software-mansion/cairo-coverage/main/scripts/install.sh | sh
 
       - name: Markdown lint
-        uses: DavidAnson/markdownlint-cli2-action@6bf21b07787794f89a243495939cd651942aeabe # v16
+        uses: DavidAnson/markdownlint-cli2-action@6bf21b07787794f89a243495939cd651942aeabe # v24.1.0
         with:
-          globs: |
-            *.md
-            !PULL_REQUEST_TEMPLATE.md
+          config: .markdownlint-cli2.jsonc
+          globs: ''
 
       - name: Verify generated Falcon NTT sources
         run: |

.markdownlint-cli2.jsonc

@@ -0,0 +1,9 @@
+{
+  "globs": [
+    "*.md",
+    "audits/README.md",
+    ".github/*.md",
+    ".claude/**/*.md",
+    "!PULL_REQUEST_TEMPLATE.md"
+  ]
+}

AGENTS.md

@@ -1,5 +1,25 @@
-# AGENTS
+# Agent Guide
 
-## Numeric literals
+Read the following guides before editing or reviewing files:
 
-Prefer numeric literals without explicit type suffixes when the compiler can infer the type; keep suffixes only when inference fails or an explicit type is required for arithmetic/disambiguation.
+- [GUIDELINES.md](GUIDELINES.md): coding and testing conventions.
+- [ARCHITECTURE.md](ARCHITECTURE.md): package layout and design constraints.
+- [CONTRIBUTING.md](CONTRIBUTING.md): contribution process, coverage, commit and PR conventions.
+
+## Critical conventions
+
+- Prefer numeric literals without type suffixes when the compiler can infer the type.
+- Prefix component storage members with the component name (for example `ERC20_balances`).
+  Preserve deployed field names and types; assess storage compatibility before changing them.
+
+## Build, test and review
+
+Follow [Development setup](CONTRIBUTING.md#development-setup) and
+[Verification](CONTRIBUTING.md#verification).
+
+For code-quality reviews, follow [this procedure](.claude/skills/code-quality/SKILL.md),
+available as `/code-quality` in Claude Code.
+
+## Using the library
+
+Use [llms.txt](llms.txt) to find packages, examples, API references and audits.

ARCHITECTURE.md

@@ -0,0 +1,99 @@
+# Architecture
+
+OpenZeppelin Contracts for Cairo provides reusable components, interfaces, utilities and
+contract presets for Starknet. Applications can depend on individual Scarb packages or use the
+`openzeppelin` umbrella package. Components separate reusable contract behavior from the
+application's choice of exposed API, authorization and composition.
+
+[Coding conventions](GUIDELINES.md) and [contribution procedures](CONTRIBUTING.md) describe how
+to work within this design.
+
+## Repository layout
+
+The root [Scarb.toml](Scarb.toml) defines the workspace. [src/lib.cairo](src/lib.cairo) re-exports
+the contract library packages under the `openzeppelin` namespace.
+
+| Path | Responsibility and dependencies |
+| --- | --- |
+| `packages/interfaces` | Shared Starknet ABI traits and dispatchers; depends on Starknet, without component implementations. |
+| `packages/introspection` | SRC5 interface registration and queries, using the shared interfaces. |
+| `packages/access` | Ownership and role-based access control; uses interfaces and introspection. |
+| `packages/account` | Account validation and execution, signature schemes and SRC9 extensions; uses interfaces, introspection, utilities and corelib compatibility imports. |
+| `packages/corelib_imports` | Isolates gated Cairo bounded-integer APIs needed by Falcon arithmetic. Its manifest uses edition `2023_10` because the pinned compiler exposes those APIs in that edition. |
+| `packages/token` | Token standards and extensions, including vaults; uses access control, interfaces, introspection and utilities. |
+| `packages/finance` | Vesting components built on access control, interfaces and token functionality. |
+| `packages/governance` | Governor, votes, timelock and multisig components; composes access, token, introspection, interfaces and utilities. |
+| `packages/security` | Initializable, pausable and reentrancy-guard components. |
+| `packages/upgrades` | Internal class-replacement operations, using Starknet syscalls. |
+| `packages/utils` | Cryptography, execution, deployment, nonce and data-structure utilities. |
+| `packages/merkle_tree` | Merkle proof and multiproof verification without a Starknet dependency. |
+| `packages/presets` | Deployable contracts that compose components and define concrete initialization and authorization. |
+| `packages/macros` | Rust procedural macros consumed through Scarb; tested with Cargo. Added directly by consumers that need macros. |
+| `packages/testing` | Foundry test helpers for downstream users; a separate dev dependency with its own version and generated API docs. |
+| `packages/test_common` | Repository test mocks, fixtures and shared assertions; depends on the implementations it exercises. |
+| `scripts/` | Release support, class-hash generation, benchmarks and Falcon reference/generation checks. |
+| `sncast_scripts/` | Deployment scripts with their own Scarb manifest. |
+| `benches/` | Contract-size benchmark results used by CI. |
+| `audits/` | Audit reports and their commit, version and scope index. |
+
+Most packages inherit the workspace version. `openzeppelin_interfaces`, `openzeppelin_utils`
+and `openzeppelin_testing` declare independent versions. Manifests are authoritative for
+versions and dependency edges. Test-only dependencies may point back to implementation
+packages; that does not make them runtime dependencies of deployed contracts.
+
+## Component composition and public APIs
+
+A `#[starknet::component]` module owns its storage, events and implementations. A consuming
+contract includes it through `component!`, a `#[substorage(v0)]` field and a component event
+variant. The contract explicitly embeds selected implementations using `#[abi(embed_v0)]`.
+Mixins group commonly used implementations, including compatibility aliases where supported.
+The [ERC20 preset](packages/presets/src/erc20.cairo) is a concrete example.
+
+Internal implementations let a contract choose access rules for operations such as minting or
+upgrading. Calling an internal operation does not itself establish application authorization.
+For example, the ERC20 preset checks ownership before calling the upgrade component. Hooks and
+immutable configuration traits let applications extend transitions without copying the
+component implementation; empty hooks and default configurations serve the simple case.
+
+## State and asset handling
+
+Component storage is embedded in the consuming contract. Field names, types, substorage
+placement and map keys determine how deployed state is interpreted. Changes to those elements
+must be assessed for storage compatibility as well as source compatibility.
+
+Token transitions centralize balance/supply accounting and event emission. Extensions attach
+to the relevant hooks; transfer callbacks and external token calls can transfer control to
+other contracts. Authorization, accounting order and reentrancy protections must therefore be
+assessed across the composed contract. ERC20 amounts use `u256`; metadata such as decimals does
+not change the unit stored in balances. Vault conversion and rounding behavior belongs to the
+ERC4626 implementation and its tests, rather than a global rounding policy for all modules.
+
+## Upgrades and versioning
+
+[UpgradeableComponent](packages/upgrades/src/upgradeable.cairo) uses Starknet's class-replacement
+syscall and emits an upgrade event. It rejects a zero class hash, while the consuming contract
+supplies the authorization policy. Class replacement preserves the contract address and
+storage; it does not prove that the new code interprets that storage compatibly.
+
+Consumers must assess upgrade compatibility against their deployed layout and the selected
+release's [compatibility guidance](https://docs.openzeppelin.com/contracts-cairo/4.x/backwards-compatibility).
+A library version number alone is not proof that an existing contract can safely upgrade.
+Install released package versions and use their matching documentation; `main` can contain
+unreleased APIs. The release procedure lives in [RELEASING.md](RELEASING.md).
+
+## Verification boundaries
+
+Cairo unit tests live with each package, while shared mocks and deployed presets exercise
+component integration and ABI behavior. Rust tests validate macro expansion and diagnostics.
+Foundry coverage exercises the development profile. CI also runs fuzzing, generated-source
+checks, release-profile Falcon tests and resource checks; commands live in
+[CONTRIBUTING.md](CONTRIBUTING.md#verification).
+
+Falcon's generated production NTT cannot be lowered by the pinned compiler in Foundry's
+non-inlining source-coverage mode. Coverage therefore exercises the generic account path;
+separate release tests verify production verifier paths and preset gas budgets. Local tests
+and resource budgets do not establish target-network support: deployment and network behavior
+need their own verification.
+
+Audit boundaries are the exact commits and scopes in [audits/README.md](audits/README.md).
+An audit of a release does not cover later changes on `main` or every downstream composition.

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socioeconomic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <contact@openzeppelin.com>. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+[homepage]: https://www.contributor-covenant.org