docs: improve developer experience and contract documentation

.github/workflows/documentation.yml

@@ -0,0 +1,39 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'contracts/**'
+      - 'docs/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'contracts/**'
+      - 'docs/**'
+
+jobs:
+  verify-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Generate Documentation
+        run: cargo doc --no-deps --all-features
+
+      - name: Verify Markdown Links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'no'
+          folder-path: 'docs'
+        continue-on-error: true
+
+      - name: Archive documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: contract-docs
+          path: target/doc

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,27 @@
+# ADR 1: Record Architecture Decisions
+
+## Status
+
+Accepted
+
+## Context
+
+We need a way to record architectural decisions made during the development of PropChain smart contracts to ensure that current and future developers understand the "why" behind significant design choices.
+
+## Decision
+
+We will use Architecture Decision Records (ADRs) to document significant architectural decisions. ADRs will be stored as markdown files in the `docs/adr/` directory.
+
+Each ADR will follow a standard template:
+- **Title**: A descriptive name for the decision.
+- **Status**: Proposed, Accepted, Rejected, Deprecated, or Superseded.
+- **Context**: The problem we are trying to solve and the requirements.
+- **Decision**: The chosen solution and the rationale.
+- **Consequences**: The implications of the decision (positive and negative).
+
+## Consequences
+
+- Improved transparency in technical decision-making.
+- Better onboarding experience for new developers.
+- A historical record of how the project evolved.
+- Small additional overhead to document decisions.

docs/best-practices.md

@@ -0,0 +1,56 @@
+# Developer Best Practices
+
+Follow these best practices when developing apps that interact with PropChain smart contracts to ensure security, efficiency, and a great user experience.
+
+## Security First
+
+### 1. Mandatory Compliance Checks
+Always check if a user is compliant before allowing high-value actions.
+```rust
+// Contract-side enforcement
+compliance_registry.require_compliance(caller)?;
+
+// Frontend-side proactive check
+if (!complianceRegistry.isCompliant(userAccount)) {
+    showComplianceOnboarding();
+}
+```
+
+### 2. Multi-Signature for Large Transfers
+For significant property movements or high-value pool actions, always use the multisig bridge or escrow mechanisms provided.
+
+### 3. Handle Errors Gracefully
+Never assume a contract call will succeed. Always handle potential error types returned by the contracts.
+
+## Gas Efficiency
+
+### 1. Batch Operations
+When managing multiple properties or performing bulk transfers, use the `safe_batch_transfer_from` method to reduce gas costs compared to individual transactions.
+
+### 2. Off-Chain Metadata
+Store large documents and heavy metadata on IPFS and only store the CID/hash on-chain. Use the `IpfsMetadataRegistry` for managed access.
+
+### 3. Minimize State Changes
+Avoid frequent updates to property metadata. Batch updates if possible or store non-critical information off-chain.
+
+## User Experience
+
+### 1. Real-Time Event Monitoring
+Subscribe to contract events (like `PropertyTransferred`, `ClaimSubmitted`, `BridgeStatusUpdated`) to provide users with immediate feedback in your application UI.
+
+### 2. Proactive Troubleshooting
+Use the `calculate_premium` or `estimate_bridge_gas` methods to show users expected costs *before* they initiate a transaction.
+
+### 3. Transparent Status Tracking
+For long-running operations like cross-chain bridging or insurance claim assessment, provide a clear status dashboard using the provided monitoring APIs.
+
+## Code Quality
+
+### 1. Use Shared Traits
+When writing new contracts that interact with PropChain components, use the trait definitions in `contracts/traits` to ensure interface compatibility.
+
+### 2. Comprehensive Testing
+Always write unit tests for your integration logic, specifically mocking different compliance statuses and contract error states.
+
+### 3. Documentation
+Document any custom business logic or contract extensions clearly, following the patterns established in this documentation suite.