diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..7b0c746
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Something isn't working correctly
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots.
+
+**Environment**
+- Aegis version: (check `/api/health` or the dashboard)
+- Docker version: `docker --version`
+- OS / platform: (e.g. Ubuntu 22.04, Synology DSM 7, macOS)
+- Arch: (amd64 / arm64)
+- Envoy version: (from docker-compose.yml)
+
+**Logs**
+```
+docker logs aegis --tail 50
+```
+
+**Additional context**
+Any other context about the problem.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..c144077
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+**What problem does this solve?**
+A clear and concise description of the problem or limitation.
+
+**Describe the solution you'd like**
+What you'd like to happen.
+
+**Alternatives considered**
+Any alternative solutions or workarounds you've considered.
+
+**Additional context**
+Screenshots, mockups, or any other context.
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..e28b8b6
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to Aegis are documented here.
+
+## [1.0.0] — 2026-05-19
+
+### Initial release
+
+**Gateway**
+- Envoy xDS control plane — manage listeners, clusters, filter chains, secrets via UI
+- Visual filter chain editor with domain/SNI routing, TLS, WebSocket, and HTTP extension support
+- Usage badges on clusters and extension configs showing how many filter chains reference them
+- Import/export gateway configuration as JSON
+- Topology view showing gateway layout
+
+**Security**
+- Real-time IP blocking with manual and automatic modes
+- Detection rules: rate flood, 404 scan, path scan, bad user-agent, 5xx flood, attack path instant response
+- Trusted IP whitelist (never auto-blocked)
+- Delegated analysis mode — forward IPs to an external analysis server
+
+**AI & Intelligence**
+- Background IP classification using Gemini, Claude, GPT, DeepSeek, or Ollama
+- Per-IP profiles with threat score, confidence, classification reasons, and AI summary
+- IP enrichment: ASN/ISP, PTR record, VPN/proxy/Tor detection, AbuseIPDB reputation
+- Owl AI chat assistant — ask about traffic, threats, and gateway configuration in plain language
+- Owl Patrol — autonomous scheduled threat sweep with configurable notification on findings
+- Ask Owl buttons on every dashboard card and config form for contextual AI help
+
+**Certificates**
+- ACME automation: Let's Encrypt, ZeroSSL, custom ACME CAs
+- HTTP-01 and DNS-01 (Cloudflare, Route53, GoDaddy) challenges
+- Manual PEM upload
+- Auto-renewal 30 days before expiry, pushed to Envoy via SDS (zero downtime)
+
+**Analytics**
+- Live request feed with method, path, status, latency, country, user-agent
+- Traffic timeline chart
+- Top IPs panel with geo, ASN, and block status
+- World map with request density
+- Device type and HTTP status code breakdowns
+- Domain traffic distribution
+- Historical mode (daily summaries) for 30d, 90d, 180d, 1y ranges
+
+**Notifications**
+- Telegram bot and webhook (Discord, Slack, generic) channels
+- Per-event toggle: IP blocked, DDoS pattern, error spike, cert expiry, daily digest
+- Notification suppression / dedup with follow-up summary
+- Event log with retry-on-failure
+- Daily digest with optional AI narrative
+
+**Auth**
+- Built-in username/password login
+- OIDC/SSO (Google, Authentik, Keycloak, any OIDC provider)
+- Optional: disable password login (SSO-only mode)
+
+**Geo**
+- Remote geo lookup via ip-api.com (free, 45 req/min)
+- Local geo lookup via MaxMind GeoLite2-City.mmdb (no rate limits)
+
+**Other**
+- Three UI themes: Dark, GitHub, Slate (light)
+- Responsive design — works on mobile
+- System resource monitor in sidebar (CPU, memory, network)
+- WebMCP browser extension support (18 registered tools)
+- Multi-arch Docker image: linux/amd64 + linux/arm64
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..17c222a
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,31 @@
+Copyright (c) 2026 Yang Yang Xie. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software ("Aegis") is provided in compiled binary form only.
+The source code is proprietary and confidential.
+
+PERMITTED USE
+Permission is granted to:
+- Use this software for personal, non-commercial, and internal business purposes
+- Run the software on your own hardware or cloud infrastructure
+- Distribute the unmodified Docker image to your own team members
+
+RESTRICTIONS
+You may not:
+- Redistribute, resell, or sublicense this software to third parties
+- Reverse engineer, decompile, or disassemble the binary
+- Attempt to derive, reconstruct, or access the source code
+- Remove or alter any proprietary notices or labels
+
+PRO LICENSE
+Certain features require a paid Pro license key. Community features are
+available free of charge. See https://github.com/axieyangb/aegis for details.
+
+DISCLAIMER
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM USE OF THIS SOFTWARE.
+
+For commercial licensing, enterprise use, or inquiries:
+yyangxie@gmail.com
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2004f42
--- /dev/null
+++ b/README.md
@@ -0,0 +1,134 @@
+# Aegis
+
+**Self-hosted Envoy gateway with AI threat analysis, TLS automation, and a real-time security dashboard.**
+
+[![Docker Pulls](https://img.shields.io/docker/pulls/axieyangb/aegis)](https://hub.docker.com/r/axieyangb/aegis)
+[![Docker Image Version](https://img.shields.io/docker/v/axieyangb/aegis?sort=semver)](https://hub.docker.com/r/axieyangb/aegis/tags)
+[![License](https://img.shields.io/badge/license-proprietary-red)](LICENSE)
+
+Aegis sits between the internet and your services. It controls Envoy Proxy via xDS, watches all traffic in real time, blocks malicious IPs automatically, manages TLS certificates, and lets you chat with your gateway through an AI assistant — all in a single Docker container.
+
+---
+
+## Quick start
+
+```bash
+docker run -d \
+  --name aegis \
+  -p 8765:8765 \
+  -v aegis_data:/data \
+  -e ADMIN_PASSWORD=changeme \
+  axieyangb/aegis:latest
+```
+
+Open `http://localhost:8765` — default login: `admin` / `changeme`
+
+### With Envoy (recommended)
+
+```bash
+curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml
+curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json
+docker compose up -d
+```
+
+---
+
+## Features
+
+| | Feature | Description |
+|---|---|---|
+| 🛡 | **Envoy xDS Control Plane** | Visual editor for listeners, clusters, filter chains — pushed live via gRPC |
+| 📊 | **Real-time Analytics** | Live request feed, top IPs, world map, device + status breakdown |
+| 🤖 | **AI Threat Analysis** | Background IP classification using Gemini / Claude / GPT / Ollama. Auto-blocks attackers |
+| 🦉 | **Owl AI Assistant** | Chat with your gateway — ask about traffic, threats, config, anything |
+| 🔒 | **TLS Automation** | ACME (Let's Encrypt, ZeroSSL), HTTP-01 & DNS-01 challenges, auto-renewal via Envoy SDS |
+| 🔔 | **Notifications** | Telegram, Discord, Slack webhooks — alert on blocks, anomalies, daily digest |
+| 🌍 | **Geo Analytics** | Country-level traffic breakdown, remote or local MaxMind GeoIP |
+| 🔑 | **Auth & SSO** | Built-in login + optional OIDC/SSO (Google, Authentik, Keycloak, etc.) |
+| 🔍 | **IP Intelligence** | Per-IP profiles with ASN, ISP, VPN/Tor detection, AbuseIPDB reputation |
+
+---
+
+## Architecture
+
+```
+Internet ──▶ Envoy Proxy ──▶ Your services
+                  │
+          gRPC xDS (port 18000)
+                  │
+             ┌────▼─────┐
+             │  Aegis   │  port 8765
+             │          │
+             │ xDS CP   │  controls Envoy live
+             │ Analytics│  reads Envoy ALS logs
+             │ AI Engine│  classifies IPs
+             │ Cert Mgr │  ACME → Envoy SDS
+             │ Dashboard│  web UI + REST API
+             └──────────┘
+```
+
+---
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `8765` | Dashboard + API port |
+| `XDS_PORT` | `18000` | Envoy gRPC xDS port |
+| `DATA_DIR` | `/data` | Persistent data directory |
+| `ADMIN_USERNAME` | `admin` | Admin username |
+| `ADMIN_PASSWORD` | `aegis` | Admin password — **change this** |
+| `AUTH_ENABLED` | `true` | Require login |
+| `BLOCK_ENABLED` | `true` | Enable auto IP blocking |
+| `NODE_ID` | `home` | Envoy node ID (must match envoy.yaml) |
+
+### Data volume
+
+Mount a volume or directory to `/data`:
+
+```
+/data/
+├── aegis.db        ← SQLite (traffic, certs, config, alerts)
+└── skills/         ← Optional: override Owl AI knowledge files
+    └── site.md     ← Custom context injected into Owl's system prompt
+```
+
+---
+
+## Docs
+
+- [Getting started](docs/getting-started.md)
+- [Envoy configuration](docs/envoy-config.md)
+- [AI setup (Owl chat + threat analysis)](docs/ai-setup.md)
+- [Notifications (Telegram, Discord, webhooks)](docs/notifications.md)
+
+---
+
+## Multi-arch
+
+`linux/amd64` and `linux/arm64` — runs on x86 servers, Raspberry Pi, Synology NAS, and Apple Silicon.
+
+```bash
+# Pin a specific version
+docker pull axieyangb/aegis:v1.0.0
+
+# Always latest
+docker pull axieyangb/aegis:latest
+```
+
+---
+
+## License
+
+Aegis is distributed as a compiled binary. Source code is proprietary. See [LICENSE](LICENSE).
+
+Community tier is **free forever**. A Pro license unlocks unlimited notification channels, longer log retention, and unlimited AI patrol sweeps.
+
+---
+
+## Support & Enterprise
+
+- **Issues & feature requests**: [GitHub Issues](https://github.com/axieyangb/aegis/issues)
+- **Enterprise licensing, custom integrations, SLA**: yyangxie@gmail.com
diff --git a/configs/starter.json b/configs/starter.json
new file mode 100644
index 0000000..b2f016d
--- /dev/null
+++ b/configs/starter.json
@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "exported_at": "2026-01-01T00:00:00Z",
+  "listeners": [
+    {
+      "name": "http_listener",
+      "json_body": "{\"name\": \"http_listener\", \"address\": {\"socketAddress\": {\"address\": \"0.0.0.0\", \"portValue\": 10080}}, \"filterChains\": [{\"filters\": [{\"name\": \"envoy.filters.network.http_connection_manager\", \"typedConfig\": {\"@type\": \"type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager\", \"statPrefix\": \"ingress_http\", \"routeConfig\": {\"virtualHosts\": [{\"name\": \"redirect_to_https\", \"domains\": [\"*\"], \"routes\": [{\"match\": {\"prefix\": \"/.well-known/acme-challenge\"}, \"route\": {\"cluster\": \"acme-renewer\"}}, {\"match\": {\"prefix\": \"/\"}, \"redirect\": {\"httpsRedirect\": true}}]}]}, \"httpFilters\": [{\"name\": \"envoy.filters.http.router\", \"typedConfig\": {\"@type\": \"type.googleapis.com/envoy.extensions.filters.http.router.v3.Router\"}}]}}]}]}",
+      "enabled": true,
+      "updated_at": 0
+    },
+    {
+      "name": "https_listener",
+      "json_body": "{\"name\": \"https_listener\", \"address\": {\"socketAddress\": {\"address\": \"0.0.0.0\", \"portValue\": 10443}}, \"listenerFilters\": [{\"name\": \"envoy.filters.listener.tls_inspector\", \"typedConfig\": {\"@type\": \"type.googleapis.com/envoy.extensions.filters.listener.tls_inspector.v3.TlsInspector\"}}], \"filterChains\": [{\"filterChainMatch\": {\"serverNames\": [\"app.yourdomain.com\"]}, \"filters\": [{\"name\": \"envoy.filters.network.http_connection_manager\", \"typedConfig\": {\"@type\": \"type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager\", \"statPrefix\": \"ingress_https\", \"routeConfig\": {\"virtualHosts\": [{\"name\": \"app_service\", \"domains\": [\"app.yourdomain.com\"], \"routes\": [{\"match\": {\"prefix\": \"/\"}, \"route\": {\"cluster\": \"my-service\", \"timeout\": \"0s\"}}]}]}, \"httpFilters\": [{\"name\": \"envoy.filters.http.router\", \"typedConfig\": {\"@type\": \"type.googleapis.com/envoy.extensions.filters.http.router.v3.Router\"}}], \"upgradeConfigs\": [{\"upgradeType\": \"websocket\"}]}}], \"transportSocket\": {\"name\": \"envoy.transport_sockets.tls\", \"typedConfig\": {\"@type\": \"type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.DownstreamTlsContext\", \"commonTlsContext\": {\"tlsCertificateSdsSecretConfigs\": [{\"name\": \"app_yourdomain_com\", \"sdsConfig\": {\"apiConfigSource\": {\"apiType\": \"GRPC\", \"transportApiVersion\": \"V3\", \"grpcServices\": [{\"envoyGrpc\": {\"clusterName\": \"xds_cluster\"}}]}, \"resourceApiVersion\": \"V3\"}}]}}}}]}",
+      "enabled": true,
+      "updated_at": 0
+    }
+  ],
+  "clusters": [
+    {
+      "name": "my-service",
+      "json_body": "{\"name\": \"my-service\", \"type\": \"STATIC\", \"connectTimeout\": \"0.25s\", \"loadAssignment\": {\"clusterName\": \"my-service\", \"endpoints\": [{\"lbEndpoints\": [{\"endpoint\": {\"address\": {\"socketAddress\": {\"address\": \"192.168.1.100\", \"portValue\": 8080}}}}]}]}}",
+      "enabled": true,
+      "updated_at": 0
+    },
+    {
+      "name": "acme-renewer",
+      "json_body": "{\"name\": \"acme-renewer\", \"type\": \"STRICT_DNS\", \"connectTimeout\": \"5s\", \"loadAssignment\": {\"clusterName\": \"acme-renewer\", \"endpoints\": [{\"lbEndpoints\": [{\"endpoint\": {\"address\": {\"socketAddress\": {\"address\": \"aegis\", \"portValue\": 8765}}}}]}]}}",
+      "enabled": true,
+      "updated_at": 0
+    }
+  ],
+  "secrets": [],
+  "extension_configs": []
+}
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..fbcde0a
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,44 @@
+services:
+  aegis:
+    image: axieyangb/aegis:latest
+    container_name: aegis
+    restart: unless-stopped
+    ports:
+      - "8765:8765"
+    volumes:
+      - aegis_data:/data
+    environment:
+      - ADMIN_USERNAME=admin
+      - ADMIN_PASSWORD=changeme        # change this
+      - AUTH_ENABLED=true
+      - BLOCK_ENABLED=true
+      - NODE_ID=home
+
+  envoy:
+    image: envoyproxy/envoy:v1.35-latest
+    container_name: envoy
+    restart: unless-stopped
+    depends_on:
+      - aegis
+    ports:
+      - "80:10080"
+      - "443:10443"
+    volumes:
+      - ./configs/starter.json:/etc/envoy/envoy.json:ro
+    command:
+      - /usr/local/bin/envoy
+      - -c
+      - /etc/envoy/envoy.json
+      - --log-level
+      - warn
+    networks:
+      default:
+        aliases:
+          - envoy
+
+networks:
+  default:
+    driver: bridge
+
+volumes:
+  aegis_data:
diff --git a/docs/ai-setup.md b/docs/ai-setup.md
new file mode 100644
index 0000000..64ef1c1
--- /dev/null
+++ b/docs/ai-setup.md
@@ -0,0 +1,72 @@
+# AI Setup
+
+Aegis has two AI features: **Intelligence Review** (background IP threat classification) and **Owl Chat** (conversational assistant).
+
+Both are optional. If no API key is configured, all other Aegis features work normally.
+
+## Supported providers
+
+| Provider | Model examples | Notes |
+|---|---|---|
+| **Gemini** (Google) | `gemini-2.0-flash`, `gemini-1.5-pro` | Free tier available |
+| **Claude** (Anthropic) | `claude-haiku-4-5-20251001`, `claude-sonnet-4-6` | Fast haiku models work well |
+| **OpenAI** | `gpt-4o-mini`, `gpt-4o` | GPT-4o-mini is cost-effective |
+| **DeepSeek** | `deepseek-chat` | Good value |
+| **Ollama** | `qwen2.5:7b`, `llama3.2:3b` | Fully local, no API key |
+
+## Intelligence Review
+
+Runs background sweeps every N minutes. Any IP with enough requests gets sent to the AI for classification:
+
+- **Type**: `human`, `bot`, `crawler`, `scanner`, `attacker`
+- **Threat score**: 0.0–1.0
+- **Auto-block**: IPs above the block threshold are blocked automatically
+
+### Configure in Settings → AI → Intelligence Review
+
+1. Toggle **Enable AI Review**
+2. Select provider and model
+3. Enter API key
+4. Set sweep interval (default: 5 min)
+5. Set alert threshold (default: 0.35) and block threshold (default: 0.65)
+   - Alert < Block is required
+
+### IP Enrichment
+
+Aegis optionally queries external databases before sending data to the AI, improving classification accuracy:
+
+| Source | Data | Cost |
+|---|---|---|
+| DNS PTR | Reverse DNS, verifies Googlebot etc. | Free |
+| ip-api.com | ASN, ISP, VPN/proxy/Tor/datacenter flags | Free, 45 req/min |
+| Known bot CIDRs | Google, Bing crawler ranges | Free |
+| AbuseIPDB | Community abuse reports, confidence score | Free tier: 1,000/day |
+
+## Owl Chat
+
+A conversational assistant that can read your live gateway state and take actions (block IPs, explain traffic, review configs, walk through setup procedures).
+
+### Configure in Settings → AI → Owl Chat Agent
+
+- Toggle **Enable Owl Chat**
+- Leave provider/model/key blank to reuse Intelligence Review settings
+- Or set a separate provider (e.g. a faster/cheaper model for chat)
+
+### What Owl can do
+
+- Answer questions about traffic patterns and security events
+- Look up IP profiles, explain threat scores
+- Block or unblock IPs
+- Review gateway configuration for issues
+- Walk you through procedures (add a domain, set up HTTP-01, configure OIDC)
+- Analyse patrol sweep results
+
+### Custom knowledge
+
+Mount a file at `/data/skills/site.md` to inject custom context into every Owl conversation — useful for documenting your server layout, special rules, or preferred procedures.
+
+## Owl Patrol
+
+Autonomous scheduled sweeps. Owl analyses recent traffic patterns and sends a notification if it finds something concerning.
+
+Configure in **Integrations → Owl Patrol** (requires at least one notification channel).
diff --git a/docs/envoy-config.md b/docs/envoy-config.md
new file mode 100644
index 0000000..9f1d56b
--- /dev/null
+++ b/docs/envoy-config.md
@@ -0,0 +1,67 @@
+# Envoy Configuration
+
+Aegis controls Envoy via xDS (ADS protocol). You configure everything through the Aegis UI — no manual YAML editing required.
+
+## How it works
+
+1. Envoy connects to Aegis at `aegis:18000` (gRPC ADS)
+2. Aegis pushes listeners, clusters, and secrets dynamically
+3. Changes in the Aegis UI take effect in Envoy within ~1 second
+
+## Static bootstrap (envoy.yaml / starter.json)
+
+Envoy needs a static bootstrap file to know where to find the xDS server. The provided `configs/starter.json` configures:
+
+- xDS server: `aegis:18000`
+- Access log: streamed to Aegis via gRPC ALS (provides real-time traffic data)
+- Node ID: `home` (must match `NODE_ID` env var in Aegis)
+
+**Do not add listeners or clusters to the bootstrap file** — manage them entirely through the Aegis Gateway UI.
+
+## Gateway concepts
+
+### Listeners
+A listener binds to a port and accepts connections. Typically:
+- One listener on port 80 (HTTP)
+- One listener on port 443 (HTTPS)
+
+### Filter chains
+Each listener can have multiple filter chains. A filter chain matches incoming connections (by SNI/domain) and routes them to a backend cluster. Each filter chain can have:
+- A TLS secret (for HTTPS)
+- A backend cluster
+- HTTP extensions (OIDC, rate limiting, Lua, etc.)
+
+### Clusters
+An upstream cluster defines where traffic goes. Types:
+- `STATIC` — fixed IP/hostname (resolved once at startup)
+- `LOGICAL_DNS` — resolve hostname once and cache
+- `STRICT_DNS` — resolve on every connection
+
+### Secrets (SDS)
+TLS certificates stored in Envoy's Secret Discovery Service. Aegis manages these automatically when you issue certificates via the Certs page.
+
+## Common setups
+
+### Reverse proxy for a single service
+
+1. Create a cluster pointing to your service (e.g. `192.168.1.10:3000`)
+2. Add an HTTPS listener on port 443
+3. Add a filter chain: domain = `app.example.com`, cluster = your cluster, TLS = your cert
+
+### Multiple domains on one server
+
+Add one filter chain per domain to your HTTPS listener. Each filter chain has its own SNI match, backend cluster, and TLS secret.
+
+### HTTP → HTTPS redirect
+
+Add a catch-all filter chain on the port-80 listener with a Lua HTTP filter that returns a 301 redirect.
+
+## Blocked IPs
+
+Blocked IPs are automatically injected as Envoy RBAC deny rules on every xDS push. You do not need to configure this.
+
+## Troubleshooting
+
+**"xDS NACK"** in the dashboard header means Envoy rejected the last config. The error message shows which resource failed. Fix the highlighted resource and save again.
+
+**Changes not applying** — check that the xDS status is "synced" (green dot). If it shows "xDS …" (grey), Envoy is not connected — verify the `NODE_ID` env var matches the node ID in your bootstrap config.
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..a8a212a
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,58 @@
+# Getting Started
+
+## Requirements
+
+- Docker and Docker Compose
+- A domain pointing to your server (for TLS / ACME)
+- Port 8765 accessible on your local network (dashboard)
+- Ports 80 and 443 open if you want Envoy to handle public traffic
+
+## 1. Download the starter files
+
+```bash
+mkdir aegis && cd aegis
+curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml
+mkdir configs
+curl -o configs/starter.json https://raw.githubusercontent.com/axieyangb/aegis/main/configs/starter.json
+```
+
+## 2. Set your admin password
+
+Edit `docker-compose.yml` and change `ADMIN_PASSWORD=changeme` to something secure.
+
+## 3. Start
+
+```bash
+docker compose up -d
+```
+
+Aegis dashboard: `http://localhost:8765`
+Default login: `admin` / (your password)
+
+## 4. Connect Envoy to Aegis
+
+The starter config in `configs/starter.json` already points Envoy's xDS endpoint at `aegis:18000`. Envoy will connect automatically once both containers are running.
+
+Open **Gateway** in the dashboard — you should see "xDS synced" in green.
+
+## 5. Add your first listener
+
+Go to **Gateway → Listeners → Add filter chain**. Configure your domain, backend cluster, and TLS secret. Changes push to Envoy immediately.
+
+## 6. Issue a TLS certificate
+
+Go to **Certificates → Add Provider** and configure an ACME provider (Let's Encrypt + HTTP-01 is the easiest). Then **Issue Certificate** for your domain.
+
+> **Note:** HTTP-01 requires the `acme-renewer` cluster and a port-80 filter chain. Open the Owl chat and say "Help me set up HTTP-01" — it will walk you through the gateway configuration.
+
+## 7. Enable AI (optional)
+
+Go to **Settings → AI**, enable Intelligence Review, and enter an API key for your chosen provider (Gemini, Claude, OpenAI, DeepSeek, or Ollama for local inference). Aegis will start classifying IPs in the background.
+
+Enable **Owl Chat** to talk to your gateway in natural language.
+
+## Next steps
+
+- [Envoy configuration reference](envoy-config.md)
+- [AI setup](ai-setup.md)
+- [Notifications](notifications.md)
diff --git a/docs/notifications.md b/docs/notifications.md
new file mode 100644
index 0000000..119e71f
--- /dev/null
+++ b/docs/notifications.md
@@ -0,0 +1,50 @@
+# Notifications
+
+Aegis can send alerts to Telegram, Discord, Slack, or any webhook endpoint.
+
+## Channel types
+
+### Telegram
+
+1. Create a bot via [@BotFather](https://t.me/BotFather) — save the bot token
+2. Start a chat with your bot (send `/start`)
+3. In Aegis: **Integrations → Add Channel → Telegram**
+4. Enter the bot token, then click **ID** to auto-detect your chat ID
+
+**Owl AI Chat via Telegram**: Enable the "Owl Chat" toggle on a Telegram channel to let Owl respond to messages sent to your bot.
+
+### Webhook (Discord, Slack, generic)
+
+- **Discord**: Server Settings → Integrations → Webhooks → New Webhook → copy URL
+- **Slack**: Create an Incoming Webhook app → copy URL
+- **Generic**: any URL that accepts a POST with a JSON body
+
+## Events
+
+Toggle which events trigger notifications:
+
+| Event | Description |
+|---|---|
+| IP Blocked | An IP was auto-blocked by a detection rule |
+| DDoS Pattern | High-volume flood detected |
+| Error Spike | Unusual 5xx error rate |
+| Client Flagged | AI classified an IP as suspicious |
+| Cert Expiry | A managed certificate is expiring soon |
+| Daily Digest | Daily summary of traffic and security events |
+| Owl Patrol | Owl found a threat during an autonomous sweep |
+
+## Suppression
+
+Duplicate alerts for the same IP/pattern within a time window are suppressed and bundled into a follow-up message (e.g. "+12 more suppressed"). This prevents alert fatigue during attacks.
+
+## Daily Digest
+
+Sent on a cron schedule (default: 08:00 daily). Includes traffic summary, top threats, cert status, and — if AI is enabled — a natural-language narrative written by Owl.
+
+Change the schedule under **Integrations → Daily Digest → Cron schedule**. Use [crontab.guru](https://crontab.guru) to build expressions.
+
+## Owl Patrol
+
+Owl analyses recent traffic on a schedule and sends a notification only when it finds something genuinely concerning. Configure the sweep interval and whether Owl is allowed to auto-block IPs during a sweep.
+
+Requires at least one notification channel to be configured.