Update readme.md

Author: wycks

readme.md

@@ -1,4 +1,4 @@
-# Python Moltbook Agent
+# Python Moltbook Agent 🦞
 
 An autonomous, Docker-ready Moltbook bot with:
 
@@ -8,13 +8,16 @@ An autonomous, Docker-ready Moltbook bot with:
 - safe dry-run mode and rate limits
 - strict lint/type/test gates for reliable changes
 
-Moltbook website: https://www.moltbook.com/
+Moltbook:
+
+- Website: https://www.moltbook.com/
+- Skill guide: https://moltbook.com/skill.md
 
 ## Join Moltbook (Required Onboarding)
 
-Read and follow the official instructions in [skill.md](skill.md) and on https://moltbook.com/skill.md.
+This agent reads and follows the official onboarding instructions from https://moltbook.com/skill.md.
 
-High-level flow:
+High-level flow for new accounts:
 
 1. Send [skill.md](skill.md) to your agent.
 2. Agent signs up and returns a claim link.
@@ -34,33 +37,78 @@ After claim is complete, set `MB_API_KEY` in your local `.env`.
 ## Quickstart
 
 1. Create and activate a Python environment.
-2. Install dependencies.
+2. Install dependencies from [pyproject.toml](pyproject.toml):
+
+```bash
+pip install -e .[dev]
+```
+
 3. Copy `.env.example` to `.env`.
 4. Set at minimum:
    - `MB_GEMINI_API_KEY`
    - `MB_API_KEY` (after claim), or keep `MB_AUTO_REGISTER=true` for onboarding flow.
 5. Optional: set `MB_RSS_FEED_URLS` to one or more comma-separated feed URLs.
 6. Run one dry-run cycle:
-   - `MB_RUNTIME__AUTONOMOUS_MODE=false`
-   - `MB_RUNTIME__RUN_ONCE=true`
-   - `python -m app.main`
 
-## AI settings
+```bash
+MB_RUNTIME__AUTONOMOUS_MODE=false
+MB_RUNTIME__RUN_ONCE=true
+python -m app.main
+```
+
+## AI Settings
 
 By default, this project is configured for the Gemini API (for the free tier). You can swap it out for any AI API.
 
 - Settings file: `configs/gemini.yaml`
 - Override path with `MB_GEMINI_CONFIG_PATH`
 - Tunables include model, temperature, top-p/top-k, function-calling mode, allowed functions, and URL lookups.
 
+## Storage and Database
+
+This project uses a local SQLite state database for operational memory.
+
+- Default DB path: `data/state.db`
+- Override path with env: `MB_STATE_DB_PATH`
+
+What is stored:
+
+- heartbeat timestamps (`last_check`)
+- rate-limit/cooldown state
+- dedup markers for ingested feed items
+- style memory samples used for tone consistency
+
+Related local files:
+
+- `data/moltbook_registration.json` (onboarding output: claim URL + verification code + issued API key)
+- `data/state.db` (runtime state)
+
+Notes:
+
+- These files are runtime artifacts and should not be committed to public repos.
+- Deleting `data/state.db` resets local memory/cooldowns/dedup state.
+
 ## Running with Docker
 
-- Start: `docker compose up -d --build`
-- Stop (keep container): `docker compose stop`
-- Down (remove container/network): `docker compose down`
-- Restart: `docker compose restart`
-- Logs: `docker compose logs -f agent`
-- Status: `docker compose ps`
+```bash
+# Start
+docker compose up -d --build
+
+# Stop (keep container)
+docker compose stop
+
+# Remove container/network
+docker compose down
+
+# Restart
+docker compose restart
+
+# Logs
+docker compose logs -f agent
+
+# Status
+docker compose ps
+```
 
 Helper scripts:
 
@@ -81,5 +129,5 @@ GitHub Actions workflow is included in [.github/workflows/ci.yml](.github/workfl
 
 ## Safety Notes
 
-- Only send Moltbook API keys to `https://www.moltbook.com` as required by [skill.md](skill.md).
 - Start in dry-run mode before enabling autonomous posting.
+- Only send Moltbook API keys to `https://www.moltbook.com`.