docs: add first version of 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 building custom attribute-based access control policies on Ethereum.
+
+The framework provides a set of common, abstract, and flexible smart contracts to simplify the creation of reusable, attribute-based criteria. These contracts, called "gatekeepers," are solution-agnostic, enforcing checks against user-provided evidence and maintaining records of those who meet the criteria.
+
+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 based on two different protocols. Indeed, for example, you can define criteria to verify token ownership or/and 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 imt.sol 2.0.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.1.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 [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
+```