diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..6edf13a
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,10 @@
+WISECLAW_ENV=development
+WISECLAW_DB_URL=sqlite:///./wiseclaw.db
+WISECLAW_OLLAMA_BASE_URL=http://127.0.0.1:11434
+WISECLAW_DEFAULT_MODEL=qwen3.5:4b
+WISECLAW_SEARCH_PROVIDER=brave
+WISECLAW_TELEGRAM_BOT_TOKEN=
+WISECLAW_BRAVE_API_KEY=
+WISECLAW_ADMIN_HOST=127.0.0.1
+WISECLAW_ADMIN_PORT=8000
+
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..becdb95
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,15 @@
+.venv/
+.venv312/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+node_modules/
+*.egg-info/
+*.tsbuildinfo
+vite.config.js
+vite.config.d.ts
+dist/
+build/
+.DS_Store
+.env
+wiseclaw.db
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..b87fdfa
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,30 @@
+# WiseClaw Architecture
+
+## Core shape
+
+WiseClaw uses a single FastAPI process with modular tool adapters:
+
+- `telegram`: inbound/outbound bot handling and whitelist checks
+- `llm`: Ollama client and simple tool-routing planner
+- `tools`: search, notes, files, terminal, and fetch tools
+- `memory`: SQLite-backed short-term and long-term state
+- `admin`: REST API for settings, logs, users, and health
+
+## Security defaults
+
+- Admin panel is localhost-only by default.
+- Secrets are modeled separately from normal settings so they can move to Keychain cleanly.
+- Terminal mode `3` is policy based:
+  - safe read-only commands auto-run
+  - mutating or networked commands require approval
+  - dangerous commands are blocked
+
+## Next implementation milestones
+
+1. Add SQLAlchemy models and Alembic migrations.
+2. Replace placeholder services with real SQLite persistence.
+3. Wire Telegram webhook or polling loop.
+4. Add Ollama-driven tool calling.
+5. Persist secrets in macOS Keychain.
+6. Build audit views and approval flows in the admin panel.
+