docs: rewrite README and docs for the full-access design, generate tool inventory

docs/index.md

@@ -1,44 +1,48 @@
-# AegisGitea MCP - Documentation
+# AegisGitea MCP documentation
 
-AegisGitea MCP is a security-first [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides controlled AI access to self-hosted Gitea repositories.
+AegisGitea MCP is a full-access [Model Context Protocol](https://modelcontextprotocol.io) bridge
+to the whole Gitea API: one tool per operation of the pinned Gitea 28.1.0 swagger (537) plus
+`gitea_api_request`, 538 tools in total. It serves them over stdio and streamable HTTP, with
+admin-token and per-user OAuth authentication, a hash-chained audit log and bounded, secret-masked
+results. Everything is enabled by default; you restrict it with configuration and the scope of
+the Gitea token.
 
-## Overview
+Gitea content is untrusted: results are labelled as data and clients must never treat them as
+instructions (see the [README](../README.md#security-notice-gitea-content-is-untrusted)).
 
-AegisGitea MCP acts as a secure bridge between AI assistants (such as Claude, Claude Code, or Cowork) and your Gitea instance. It exposes read tools and opt-in write tools while enforcing per-user OAuth, repository authorization, policy checks, rate limiting, and tamper-evident audit logging.
+Requires Python 3.10 or newer. License: MIT.
 
-**Version:** 0.1.0 (Alpha)  
-**License:** MIT  
-**Requires:** Python 3.10+
-
-## Documentation
+## Documents
 
 | Document | Description |
 |---|---|
-| [Getting Started](getting-started.md) | Installation and first-time setup |
-| [Configuration](configuration.md) | All environment variables and settings |
-| [API Reference](api-reference.md) | HTTP endpoints and MCP tools |
-| [Raw API Dispatch](raw-api.md) | The generic `gitea_request` escape-hatch tool |
-| [Architecture](architecture.md) | System design and data flow |
-| [Security](security.md) | Authentication, rate limiting, and audit logging |
-| [Deployment](deployment.md) | Docker and production deployment |
+| [README](../README.md) | Overview, quick start, scopes, auth modes, client configs |
+| [Getting started](getting-started.md) | Fresh clone to a working server, the `setup` command |
+| [Configuration](configuration.md) | Every environment variable, default and validation rule |
+| [Tool inventory](tools.md) | Generated list of all tools with method, path and flags |
+| [Raw API tool](raw-api.md) | `gitea_api_request` for endpoints newer than the pinned spec |
+| [Architecture](architecture.md) | Catalog, executor, server, transports, auth, request flow |
+| [Deployment](deployment.md) | Docker, reverse proxy and TLS, OAuth application, upgrades |
+| [Hardening](hardening.md) | Checklist for running a full-access server |
+| [Audit logging](audit-logging.md) | Event fields, integrity validation, rotation |
+| [Troubleshooting](troubleshooting.md) | Startup problems, error kinds, OAuth and HTTP issues |
+| [Packaging](packaging.md) | Building and the dev and stable package channels |
+| [Security](security.md) | Threat model and security controls |
+| [Roadmap](roadmap.md) | State of the project and known limits |
+| [ADRs](adr/0001-full-access-by-default.md) | Architecture decision records 0001 to 0006 |
+| [Codebase audit and chunk plan](audit.md) | Audit of the 0.x code and the plan for 1.0.0 |
+| [Research notes](research/sdk-oauth-gitea.md) | SDK, OAuth and Gitea facts with sources |
 
-## Quick Start
+## Quick start
 
 ```bash
-# 1. Clone and install
-git clone <repo-url>
+git clone https://git.hiddenden.cafe/Hiddenden/AegisGitea-MCP.git
 cd AegisGitea-MCP
-make install-dev
-
-# 2. Configure
-cp .env.example .env
-# Edit .env with your Gitea URL and token
-
-# 3. Generate an API key
-make generate-key
-
-# 4. Run
-make run
+uv sync
+uv run aegis-gitea-mcp setup          # verifies Gitea, writes .env, prints client configs
+MCP_TRANSPORT=http uv run aegis-gitea-mcp serve
+curl http://127.0.0.1:8080/health
 ```
 
-The server starts at `http://localhost:8080`.
+The tool inventory and the README tool summary are generated by `scripts/check_docs.py`; CI
+fails when they drift from the catalog.