Adding READMEs

README.md

@@ -1,3 +1,98 @@
-# excubiae
+# Excubiae
 
-an on-chain flexible & modular framework for implementing custom gatekeepers.
+Excubiae is a composable framework for creating custom attribute-based access control policies on EVM-compatible networks.
+
+It provides a set of abstract and flexible smart contracts, known as "gatekeepers," to streamline the definition of reusable criteria. These solution-agnostic contracts enforce checks against user-provided evidence and track those who satisfy the requirements.
+
+This approach enables seamless interoperability across different protocols. For instance, a single check could combine verifiable attributes from Semaphore and MACI, ensuring flexible and composable access control. Indeed, for example, you can define criteria to verify token ownership and/or validate a zero-knowledge proof (ZKP). Using these criteria, you can create a policy to enforce the checks and integrate it seamlessly into your smart contract logic. A practical use case might involve requiring verification before registering a new voter for a poll (e.g., in a MACI-based voting system).
+
+You can learn more in this [design document](https://hackmd.io/@0xjei/B1RXoTh71e).
+
+> [!IMPORTANT]  
+> Excubiae is currently in the MVP stage. Official documentation and audits are not yet available. Expect fast development cycles with potential breaking changes — use at your own risk!
+
+## Installation
+
+Clone this repository:
+
+```bash
+git clone https://github.com/privacy-scaling-explorations/excubiae.git
+```
+
+and install the dependencies:
+
+```bash
+cd excubiae && yarn
+```
+
+## Usage
+
+### Format
+
+Run [Prettier](https://prettier.io/) to check formatting rules:
+
+```bash
+yarn format
+```
+
+or to automatically format the code:
+
+```bash
+yarn format:write
+```
+
+### Lint
+
+Combination of [ESLint](https://eslint.org/) & [Solhint](https://protofire.github.io/solhint/)
+
+```bash
+yarn lint
+```
+
+### Testing
+
+Test the code:
+
+```bash
+yarn test
+```
+
+### Build
+
+Build all packages & apps:
+
+```bash
+yarn build
+```
+
+Compile all contracts:
+
+```bash
+yarn compile:contracts
+```
+
+### Releases
+
+1. Bump a new version of the package with:
+
+```bash
+yarn version:bump <package-name> <version>
+# e.g. yarn version:bump excubiae 0.2.0
+```
+
+This step creates a commit and a git tag.
+
+2. Push the changes to main:
+
+```bash
+git push origin main
+```
+
+3. Push the new git tag:
+
+```bash
+git push origin <package-name>-<version>
+# e.g. git push origin excubiae-v0.2.0
+```
+
+After pushing the new git tag, a workflow will be triggered and will publish the package on [npm](https://www.npmjs.com/) and release a new version on Github with its changelogs automatically.

packages/contracts/contracts/README.md

@@ -1 +1,75 @@
-contracts/README.md
+# Excubiae Smart Contracts
+
+This package contains the smart contracts which define the composable framework for building custom attribute-based access control policies on Ethereum.
+
+You can learn more in the Smart Contracts section of this [design document](https://hackmd.io/@0xjei/B1RXoTh71e#Smart-Contracts).
+
+> [!IMPORTANT]  
+> Excubiae is currently in the MVP stage. Official documentation and audits are not yet available. Expect fast development cycles with potential breaking changes — use at your own risk!
+
+## Installation
+
+You can install the excubiae contracts with any node package manager (`bun`, `npm`, `pnpm`,`yarn`):
+
+```bash
+bun add @excubiae/contracts
+npm i @excubiae/contracts
+pnpm add @excubiae/contracts
+yarn add @excubiae/contracts
+```
+
+## Usage
+
+This package is configured to support the combination of [Hardhat](https://hardhat.org/) and [Foundry](https://book.getfoundry.sh/), see the Hardhat's [documentation](https://hardhat.org/hardhat-runner/docs/advanced/hardhat-and-foundry) to learn more.
+
+### Compile contracts
+
+Compile the smart contracts with [Hardhat](https://hardhat.org/):
+
+```bash
+yarn compile:hardhat
+```
+
+Compile the smart contracts with Foundry's [Forge](https://book.getfoundry.sh/forge/):
+
+```bash
+yarn compile:forge
+```
+
+Run both in one command:
+
+```bash
+yarn compile
+```
+
+### Testing
+
+Run [Mocha](https://mochajs.org/) to test the contracts (Typescript tests):
+
+```bash
+yarn test:hardhat
+```
+
+Run Foundry's [Forge](https://book.getfoundry.sh/forge/) to test the contracts (Solidity tests):
+
+```bash
+yarn test:forge
+```
+
+Run both in one command:
+
+```bash
+yarn test
+```
+
+You can also generate a test coverage report:
+
+```bash
+yarn test:coverage
+```
+
+Or a test gas report:
+
+```bash
+yarn test:report-gas
+```