added documentations

doc/getting-started.md

@@ -0,0 +1,109 @@
+# Getting Started
+
+This guide takes you from a fresh clone to a working AI assistant that can read your EVE Online
+account and act on it when you ask.
+
+## 1. Prerequisites
+
+- **[uv](https://docs.astral.sh/uv/)** — the Python project/dependency manager familiar is built
+  around. Install it first (see the uv docs for your platform).
+- **Python 3.11+** — uv will fetch a suitable interpreter if you don't have one.
+- An **EVE Online account** (for the authenticated tools; public market/universe lookups work
+  without one).
+- An MCP-capable client: **Claude Code**, **Claude Desktop**, **Cowork**, or any other MCP client.
+
+## 2. Install
+
+```bash
+uv sync          # install the project and all dependencies (incl. the dev group)
+```
+
+There is no separate build step for local use. `uv run familiar` runs the server straight from
+source.
+
+## 3. Log in (EVE SSO)
+
+familiar uses EVE's Single Sign-On with PKCE — no client secret, nothing to configure. Run the
+login once **per character**:
+
+```bash
+uv run familiar login    # opens your browser to the EVE SSO consent page
+```
+
+The browser opens CCP's login page. Approve the requested scopes; the callback lands on
+`localhost:8765`, the code is exchanged for tokens, and the (rotating) refresh token is stored
+**encrypted** on disk. You'll see a "login complete" page — close the tab and return to the terminal.
+
+To add more characters, switch EVE accounts in the browser and run `login` again. All characters live
+in one encrypted store:
+
+```bash
+uv run familiar status   # list logged-in characters
+uv run familiar logout NAME   # forget one character (by name or id)
+uv run familiar logout        # forget ALL characters
+```
+
+> **Changing scopes:** if the set of requested scopes changes (e.g. a new familiar version adds
+> tools), you must log in again to grant them.
+
+See [Authentication](authentication.md) for the full flow and the scope list.
+
+## 4. Connect to your AI client
+
+### Claude Code
+
+```bash
+claude mcp add familiar -- uv --directory /path/to/familiar run familiar
+```
+
+### Claude Desktop
+
+Add this to `claude_desktop_config.json` (replace the directory with your clone's absolute path):
+
+```json
+{
+  "mcpServers": {
+    "familiar": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/familiar", "run", "familiar"]
+    }
+  }
+}
+```
+
+The client launches `uv run familiar` with no arguments, which starts the MCP server over **stdio** —
+the transport MCP clients speak.
+
+## 5. First queries
+
+Ask in natural language. The AI picks the right tools:
+
+- *"Is the familiar server up?"* → calls `ping`.
+- *"What's Tritanium worth in Jita?"* → `get_market_price`.
+- *"Compare Plex prices across all trade hubs."* → `compare_hubs`.
+- *"How much ISK do I have across all my characters?"* → wallet tools, per character.
+- *"Where are my characters right now?"* → location tools.
+- *"Set a waypoint to Amarr for my main."* → `set_waypoint` (a **write** — previewed first; see below).
+
+## 6. Write actions
+
+Write tools (send mail, set waypoints, edit contacts/fittings, fleet commands, open windows, PI) are
+**enabled by default**, but every write is still previewed unless you pass `confirm=true`, and each
+executed write is logged. To block all writes globally:
+
+```bash
+uv run familiar writes disable    # turn writes off
+uv run familiar writes enable     # turn them back on
+uv run familiar writes            # show current state
+```
+
+Full details in [Write Safety](write-safety.md).
+
+## 7. Verify everything works
+
+```bash
+uv run pytest          # full test suite (fails under 80% coverage)
+uv run familiar        # start the server manually (Ctrl-C to stop) — it waits on stdio
+```
+
+If `uv run familiar` starts without error and `familiar status` shows your characters, you're ready.