add docs

docs/architecture.md

@@ -0,0 +1,28 @@
+# Obsero System Architecture
+
+## Components
+
+- Probe: Performs observations and signs data.
+- IPFS Node: Stores full proofs.
+- Smart Contract: Anchors proof hashes and CIDs.
+- Blockchain: Publicly verifiable ledger.
+- Explorer/Client: Visualization and validation of proofs.
+
+## Workflow
+
+1. Probe observes service and creates JSON proof.
+2. Probe signs and uploads proof to IPFS.
+3. Proof hash and CID are submitted on-chain.
+4. Public verification of data integrity is possible.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A[Observer Probe] --> B[Ping Target]
+    B --> C[Generate JSON Observation]
+    C --> D[Hash and Sign Observation]
+    D --> E[Upload JSON to IPFS]
+    E --> F[Submit Hash and CID to Smart Contract]
+    F --> G[Proof Publicly Verifiable]
+```

docs/contract.md

@@ -0,0 +1,21 @@
+# Obsero Smart Contract Specification
+
+The smart contract anchors proof hashes on the Base blockchain.
+
+## Functions
+
+```solidity
+function submitProof(bytes32 hash, string calldata cid, uint256 timestamp) external;
+```
+
+## Events
+
+```solidity
+event ProofSubmitted(address indexed observer, bytes32 hash, string cid, uint256 timestamp);
+```
+
+## Requirements
+
+- The hash must match the signed JSON proof.
+- CID must point to a valid IPFS document.
+- Timestamps must be reasonable compared to block timestamp.

docs/protocol.md

@@ -0,0 +1,18 @@
+# Obsero Protocol Overview
+
+Obsero is a decentralized observability protocol ensuring verifiable monitoring of Web2 and Web3 infrastructures through cryptographic proofs.
+
+## Core Principles
+
+- Decentralization of monitoring
+- Verifiable and immutable proofs
+- Independence from centralized providers
+- Transparency and auditability
+
+## Flow Overview
+
+1. Probe executes a service observation (e.g., HTTP ping).
+2. JSON proof is generated.
+3. Proof is hashed (SHA256) and signed (ECDSA).
+4. Proof is uploaded to IPFS.
+5. Hash, CID, and timestamp are submitted to a smart contract on Base blockchain.

docs/roadmap.md

@@ -0,0 +1,16 @@
+# Obsero Roadmap
+
+## Phases
+
+- Proof of Concept
+- Public Alpha Release
+- Full Blockchain Integration (Base L2)
+- IPFS Persistence Hardening
+- Governance DAO Setup
+- Multichain Deployment
+- Premium Features (notifications, custom dashboards)
+
+## Goals
+
+- Build a decentralized monitoring standard.
+- Enable trustless, community-driven infrastructure observability.

docs/security.md

@@ -0,0 +1,16 @@
+# Obsero Security Model
+
+Obsero ensures resilience and integrity through multiple layers of protection.
+
+## Threats Addressed
+
+- Proof forgery: ECDSA signature validation
+- Data tampering: Immutable hashing
+- Spam attacks: Possible stake or fee mechanism
+- Replay attacks: Timestamp uniqueness
+
+## Trust Model
+
+- Each observation is individually signed.
+- Trust shifts from the observer to cryptographic proofs.
+- Full auditability through IPFS and blockchain.

docs/usage.md

@@ -0,0 +1,21 @@
+# Using Obsero Probe
+
+## Requirements
+
+- Go 1.21+
+- Local or remote IPFS node
+- Ethereum private key
+
+## Steps
+
+1. Launch the probe with a target:
+
+```bash
+go run ./cmd/obsero-probe --target https://example.com --output proof.json --ipfs
+```
+
+2. Review the generated proof file.
+
+3. Validate the signature and hash.
+
+4. Use the IPFS CID and proof hash to submit on-chain.