docs: fix the claude mcp add form, pin the package index, document known limitations

The --env option swallowed the server name, so the stdio command is reordered. uvx now always
names the project registry because the package name is not registered on public PyPI.
README gains a Known limitations section, the READ_ONLY wording is corrected, packaging.md
warns about --extra-index-url and the Le Chat admin requirement is mentioned.

docs/configuration.md

@@ -95,7 +95,7 @@ listed nor callable.
 
 | Variable | Default | Rules |
 |---|---|---|
-| `READ_ONLY` | `false` | Expose only read-only (GET) operations. `gitea_api_request` stays listed but accepts only GET. |
+| `READ_ONLY` | `false` | Expose only operations annotated read-only (GET plus a few non-mutating POST endpoints such as the render endpoints). `gitea_api_request` stays listed but accepts only GET. |
 | `TOOLSETS` | `all` | Comma separated domains: `admin`, `repo`, `issue`, `pull`, `release`, `wiki`, `org`, `team`, `user`, `actions`, `hook`, `package`, `notification`, `misc`, or `all`. Unknown domains are rejected. `gitea_api_request` belongs to `misc`. |
 | `DISABLED_TOOLS` | empty | Exact tool names to hide, lowercased on load. An unknown name is a startup error that lists the bad names. |
 

docs/deployment.md

@@ -67,7 +67,7 @@ Check it: `curl http://127.0.0.1:8080/health`.
 
 Terminate TLS at a reverse proxy. `PUBLIC_BASE_URL` must be the public https URL (it is required
 for OAuth, and http is only accepted for loopback hosts). Mistral Le Chat needs a valid public
-certificate.
+certificate, and adding a connector there may require workspace admin rights.
 
 Caddy:
 

docs/getting-started.md

@@ -96,10 +96,14 @@ make validate-audit
 With `uvx`, no checkout is needed:
 
 ```bash
-GITEA_URL=https://git.example.com GITEA_TOKEN=<your-gitea-token> uvx aegis-gitea-mcp
+GITEA_URL=https://git.example.com GITEA_TOKEN=<your-gitea-token> \
+  uvx --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp
 ```
 
-The package comes from the Gitea package registry, see [packaging.md](packaging.md).
+The package comes from the Gitea package registry, see [packaging.md](packaging.md). Always pass
+the `--index`: the name is not registered on public PyPI, and a bare `uvx aegis-gitea-mcp` would
+resolve there. From a clone use
+`uv run --directory /path/to/AegisGitea-MCP aegis-gitea-mcp serve`.
 
 ## Where state lives
 

docs/packaging.md

@@ -44,28 +44,46 @@ Dependencies are pinned in `uv.lock`; `uv sync` reproduces the environment.
 
 ## Install from the Gitea registry
 
+Index URL: `https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/`
+
 Stable:
 
 ```bash
-uv pip install \
-  --extra-index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ \
-  aegis-gitea-mcp
-
-# or run it without installing into an environment:
+# run it without installing into an environment (recommended):
 uvx --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp
+
+# or install it into an environment:
+uv pip install --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp
 ```
 
-Dev (newest pre-release build):
+Dev (newest pre-release build, package `aegis-gitea-mcp-dev`):
 
 ```bash
-uv pip install --pre \
-  --extra-index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ \
-  aegis-gitea-mcp-dev
+uvx --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ --prerelease allow aegis-gitea-mcp-dev
 ```
 
-The registry holds only this project's packages and does not proxy PyPI, so it is added as an
-extra index and the dependencies (`mcp`, `httpx`, ...) still come from PyPI. With `pip` use
-`--extra-index-url` the same way.
+The registry holds only this project's packages and does not proxy PyPI, so it is added with
+`--index` and the dependencies (`mcp`, `httpx`, ...) still come from PyPI. uv's default index
+strategy (`first-index`) takes a package from the first index that has it and never mixes
+versions across indexes, so with `--index` the name `aegis-gitea-mcp` is always taken from
+this registry, even if somebody registers it on PyPI.
+
+Do not use `--extra-index-url` with `pip`. It merges the indexes, and `pip` picks the highest
+version from either: whoever publishes `aegis-gitea-mcp` on PyPI with a higher version number
+wins (dependency confusion), and the package would run with your Gitea token in its
+environment. With `pip`, fetch the wheel from this registry alone, then install it:
+
+```bash
+pip download --no-deps --index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp -d wheels/
+pip install wheels/aegis_gitea_mcp-*.whl
+```
+
+The name is not registered on public PyPI. Publishing there is intentionally not configured, but
+the owner should reserve both names (`aegis-gitea-mcp`, `aegis-gitea-mcp-dev`) on PyPI so nobody
+else can take them. Until then every install command above must name the index.
+
+To run from a clone instead of a registry:
+`uv run --directory /path/to/AegisGitea-MCP aegis-gitea-mcp serve`.
 
 ## Publishing
 

docs/troubleshooting.md

@@ -22,8 +22,10 @@ Gitea's sanitized message, and the audit log has one event per call (see
 
 stdout carries only JSON-RPC. If a wrapper script prints to stdout before the server starts, the
 client fails to parse the stream. Logs go to stderr; look at the client's MCP server log.
-`uvx` needs access to the package index that hosts `aegis-gitea-mcp`, see
-[packaging.md](packaging.md).
+`uvx` needs access to the package index that hosts `aegis-gitea-mcp`: pass
+`--index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/`, see
+[packaging.md](packaging.md). If you register the server with `claude mcp add`, put `--env`
+before `--transport stdio` and the server name, as `setup` prints it.
 
 ## Tool calls fail