Redesign docs presentation

Author: bnovik0v

README.md

@@ -174,7 +174,7 @@ agentproof verify challenge.json response.json
 
 ## Demo
 
-A runnable local demo lives in [`demo/`](/home/borislav/VSCode/agentproof/demo).
+A runnable local demo lives in [`demo/`](https://github.com/bnovik0v/agentproof/tree/main/demo).
 
 Run it with:
 
@@ -214,7 +214,7 @@ uv run mkdocs build --strict
 
 - PyPI: https://pypi.org/project/agentproof-ai/
 - Docs: https://bnovik0v.github.io/agentproof/
-- Demo: [demo/README.md](/home/borislav/VSCode/agentproof/demo/README.md)
+- Demo: [demo/README.md](https://github.com/bnovik0v/agentproof/blob/main/demo/README.md)
 - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License

docs/api.md

@@ -1,22 +1,91 @@
 # API
 
-## Public entry points
+## Public imports
 
 ```python
 from agentproof import generate_challenge, solve_challenge, verify_response
 from agentproof import ChallengeSpec, Challenge, AgentResponse, VerificationResult
 ```
 
-## ChallengeSpec
+## `ChallengeSpec`
+
+Used to request a challenge.
+
+Fields:
 
 - `challenge_type`
 - `ttl_seconds`
 - `difficulty`
 - `options`
 
-## VerificationResult
+Example:
+
+```python
+spec = ChallengeSpec(
+    challenge_type="semantic_math_lock",
+    ttl_seconds=90,
+    options={"topic": "security", "word_count": 7},
+)
+```
+
+## `Challenge`
+
+Represents an issued challenge payload.
+
+Important fields:
+
+- `challenge_id`
+- `challenge_type`
+- `prompt`
+- `issued_at`
+- `expires_at`
+- `data`
+- `version`
+
+## `AgentResponse`
+
+Represents the response returned by a client or reference solver.
+
+Important fields:
+
+- `challenge_id`
+- `challenge_type`
+- `payload`
+
+## `VerificationResult`
+
+Returned by `verify_response(...)`.
+
+Fields:
 
 - `ok`
 - `reason`
 - `details`
 
+Common success value:
+
+```json
+{
+  "ok": true,
+  "reason": "ok",
+  "details": {
+    "nonce": "223",
+    "hash": "00bf9b61..."
+  }
+}
+```
+
+Common failure values:
+
+- `challenge_id_mismatch`
+- `challenge_type_mismatch`
+- `challenge_expired`
+- `missing_nonce`
+- `missing_hash`
+- `hash_mismatch`
+- `insufficient_difficulty`
+- `missing_text`
+- `wrong_word_count`
+- `required_word_constraint_failed`
+- `initial_sum_mismatch`
+

docs/concepts.md

@@ -1,23 +1,75 @@
-# Concepts
+# Challenge Types
 
-## Challenge families
+`agentproof` currently ships two built-in challenge families.
 
-`agentproof` currently ships two built-in challenge families:
+## `proof_of_work`
 
-- `proof_of_work`
-- `semantic_math_lock`
+Use this when you want a deterministic compute task with no natural-language component.
 
-Each family supports:
+What the agent does:
 
-- generation
-- solving with the reference implementation
-- verification
+- reads the payload
+- searches for a nonce
+- returns a nonce and hash pair
 
-## Determinism
+What the server verifies:
 
-Verification logic should be machine-checkable and stable. The library avoids fuzzy scoring.
+- challenge ID matches
+- response is not expired
+- hash recomputes correctly
+- hash satisfies the required difficulty
 
-## Extensibility
+Typical use cases:
 
-Challenge families implement a shared protocol, which keeps custom handlers isolated from the public API.
+- cheap anti-abuse friction
+- deterministic smoke tests
+- baseline challenge-response verification
+
+## `semantic_math_lock`
+
+Use this when you want a readable challenge that still has exact measurable constraints.
+
+What the agent does:
+
+- reads required words and word-count rules
+- produces text that matches all constraints
+- returns the text in structured JSON
+
+What the server verifies:
+
+- challenge ID matches
+- response is not expired
+- exact word count
+- required words appear exactly once
+- initial-letter ASCII sum matches the target
+
+Typical use cases:
+
+- reverse-CAPTCHA experiments
+- structured agent behavior checks
+- demos where human-readable prompts matter
+
+## Determinism matters
+
+`agentproof` intentionally avoids fuzzy verification.
+
+Each built-in challenge is designed so the server can produce a clear yes/no result and, when it
+fails, a concrete failure reason such as:
+
+- `challenge_expired`
+- `hash_mismatch`
+- `wrong_word_count`
+- `required_word_constraint_failed`
+- `initial_sum_mismatch`
+
+## Extending the library
+
+Challenge families implement a shared internal protocol:
+
+- generate
+- solve
+- verify
+
+That keeps custom challenge logic isolated from the public API while preserving a consistent
+library interface.
 

docs/examples.md

@@ -5,16 +5,19 @@
 ```python
 from agentproof import ChallengeSpec, generate_challenge, solve_challenge, verify_response
 
-challenge = generate_challenge(ChallengeSpec(challenge_type="proof_of_work", difficulty=16))
+challenge = generate_challenge(
+    ChallengeSpec(challenge_type="proof_of_work", difficulty=16, ttl_seconds=120)
+)
 response = solve_challenge(challenge)
 result = verify_response(challenge, response)
+
 assert result.ok
 ```
 
 ## Semantic math lock
 
 ```python
-from agentproof import ChallengeSpec, generate_challenge, solve_challenge
+from agentproof import ChallengeSpec, generate_challenge, solve_challenge, verify_response
 
 challenge = generate_challenge(
     ChallengeSpec(
@@ -23,5 +26,56 @@ challenge = generate_challenge(
     )
 )
 response = solve_challenge(challenge)
+result = verify_response(challenge, response)
+
+assert result.ok
+print(response.payload["text"])
+```
+
+## Manual verification in a service
+
+```python
+from agentproof import AgentResponse, Challenge, verify_response
+
+challenge = Challenge(**challenge_payload_from_storage)
+response = AgentResponse(**response_payload_from_client)
+result = verify_response(challenge, response)
+
+if result.ok:
+    allow_request()
+else:
+    reject_request(result.reason)
+```
+
+## Failure example
+
+If the client sends the wrong number of words for `semantic_math_lock`, the result looks like:
+
+```json
+{
+  "ok": false,
+  "reason": "wrong_word_count",
+  "details": {
+    "actual": 3,
+    "expected": 7
+  }
+}
 ```
 
+## Local demo
+
+The repository ships a runnable local demo in the
+[`demo/` directory on GitHub](https://github.com/bnovik0v/agentproof/tree/main/demo).
+
+Run it with:
+
+```bash
+uv run python demo/app.py
+```
+
+The demo lets you:
+
+- generate challenges
+- auto-solve them
+- inspect the raw JSON
+- tamper with the response and watch verification fail

docs/getting-started.md

@@ -0,0 +1,57 @@
+# Getting Started
+
+## Install
+
+```bash
+pip install agentproof-ai
+```
+
+The published distribution name is `agentproof-ai`, but the import name is `agentproof`.
+
+## Basic roundtrip
+
+```python
+from agentproof import ChallengeSpec, generate_challenge, solve_challenge, verify_response
+
+challenge = generate_challenge(
+    ChallengeSpec(challenge_type="proof_of_work", difficulty=8, ttl_seconds=60)
+)
+response = solve_challenge(challenge)
+result = verify_response(challenge, response)
+
+print(challenge.to_dict())
+print(response.to_dict())
+print(result.to_dict())
+```
+
+## CLI roundtrip
+
+```bash
+agentproof generate proof_of_work --difficulty 16 --output challenge.json
+agentproof solve challenge.json --output response.json
+agentproof verify challenge.json response.json
+```
+
+## Service flow
+
+In a real application:
+
+1. Your backend generates a challenge and returns it to the client.
+2. The client agent solves it.
+3. The client sends the response back.
+4. Your backend verifies it before allowing the next step.
+
+## Local demo
+
+Run the demo app from the repository root:
+
+```bash
+uv run python demo/app.py
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8765
+```
+