docs: add OSS contribution guidelines, code of conduct and agent instructions

Author: siyovush-hamidov

AGENTS.md

@@ -0,0 +1,42 @@
+# AI Agent Instructions for On-Chain SSI
+
+## Project Context
+This is an On-Chain Self-Sovereign Identity (SSI) architecture project. It enables organizations to issue and verify decentralized digital identities anchored on the blockchain using the `did:ethr` standard and CRSet (Credential Revocation Set) management.
+The repository is a **monorepo** containing smart contracts, frontend, and backend packages.
+
+## Tech Stack & Global Rules
+- **Node.js**: Strict requirement of `>= 22.12.0` (Do NOT use Node 20.x due to Hardhat 3 and Vite 7 constraints).
+- **Package Manager**: `npm` (version `>= 10.0.0`). Do not use `yarn` or `pnpm`.
+- **Language**: TypeScript is used everywhere (contracts and frontend).
+
+## Package-Specific Guidelines
+
+### 1. Smart Contracts (`packages/trust-anchor-did-ethr`)
+- **Framework**: Hardhat 3 with Viem (`@nomicfoundation/hardhat-toolbox-viem`).
+- **Solidity Version**: `0.8.28`.
+- **Deployment**: We use **Hardhat Ignition** (`@nomicfoundation/hardhat-ignition`). Do not use the legacy `hardhat-deploy` plugins.
+- **Testing**: Tests are written using Hardhat and Viem.
+- **Commands**:
+  - Compile: `npm run compile` (or `npx hardhat compile`)
+  - Test: `npx hardhat test`
+  - Local Node: `npx hardhat node`
+
+### 2. Frontend (`packages/demo-app-frontend`)
+- **Framework**: React 19 + Vite 7.
+- **Blockchain Interaction**: `wagmi` (v3) + `viem` (v2).
+- **Styling**: Tailwind CSS + Vanilla CSS (`index.css`). Use modern, clean aesthetics.
+- **Linting/Formatting**: ESLint and Prettier are strictly enforced via Husky pre-commit hooks. Ensure code passes `npm run lint` before committing.
+- **Commands**:
+  - Dev server: `npm run dev`
+  - Build: `npm run build`
+
+## Workflows
+
+### Git & Code Commits
+- We use Husky pre-commit hooks to lint and format code automatically. Do not bypass them unless explicitly instructed.
+- When generating Markdown documentation, ensure compliance with `markdownlint` (we ignore MD013 / line lengths by default).
+
+### Implementation Steps (For AI Agents)
+1. **Plan Mode**: Analyze the file structure, specifically checking the `package.json` in the respective sub-package before importing new libraries. Ask for clarification if unsure about the system architecture.
+2. **Build Mode**: Write clean, modular TypeScript code. Document any new smart contract functions with NatSpec comments. 
+3. **Verification**: Always double-check your output against the specific Vite or Hardhat versions we are using.

CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders 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, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to On-Chain SSI
+
+Thank you for considering contributing to On-Chain SSI!
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How Can I Contribute?
+
+### Reporting Bugs
+This section guides you through submitting a bug report.
+- **Ensure the bug was not already reported** by searching on GitHub under Issues.
+- If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and a clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
+
+### Suggesting Enhancements
+- Open a new issue with the label `enhancement`.
+- Provide a clear and detailed explanation of the feature you want and why it's important.
+
+### Pull Requests
+1. **Fork the repo** and create your branch from `main`.
+2. **Install dependencies** using `npm install` (we use NPM >= 10.0.0 and Node.js >= 22.12.0).
+3. **Make your changes**. If you've added code that should be tested, add tests.
+4. **Ensure the test suite passes**: Run `npx hardhat test` for contracts or `npm run lint` for frontend changes.
+5. **Issue that pull request!**
+
+## Development Guidelines
+
+### 1. Smart Contracts
+- Located in `packages/trust-anchor-did-ethr`.
+- We use Hardhat Ignition for deployments and Viem for testing.
+- Write Solidity 0.8.28 and include NatSpec comments.
+
+### 2. Frontend
+- Located in `packages/demo-app-frontend`.
+- Stack: React 19, Vite 7, Wagmi 3, and Viem 2.
+- Adhere to the ESLint and Prettier rules enforced via our Husky pre-commit hooks.
+
+### 3. Documentation
+- Our documentation is hosted on GitBook.
+- All documentation Markdown files are in the `docs/` folder. Use GitBook-flavored Markdown.
+
+## Any Questions?
+Feel free to open an issue with the label `question` and we will get back to you!

README.md

@@ -135,7 +135,7 @@ The comprehensive project features and setup information are part of the GitBook
 - **[Smart Contracts](packages/trust-anchor-did-ethr/README.md)** - Detailed smart contract documentation
 - **[Demo Application](packages/demo-app-frontend/README.md)** - Frontend application guide
 
-To contribute to the documentation, simply modify the Markdown files in the `docs/` directory and create a Pull Request. GitBook will automatically synchronize the changes via its native GitHub App.
+To contribute to the documentation or the codebase, please review our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md). For documentation specifically, simply modify the Markdown files in the `docs/` directory and create a Pull Request. GitBook will automatically synchronize the changes via its native GitHub App.
 
 ## License
 

docs/images/did-method-for-ipfs-based-crset-managed-through-on-chain-did-document.pdf

@@ -0,0 +1 @@
+Subproject commit 7b69cc169bd2881888e0d5bf12f8b1244a042191