docs(ai): move agent rules to ai/skills and add an AI development sandbox (#1498)

The sandbox provides an isolated Docker environment for AI-assisted development
(OpenCode + Claude Code + Qwen Code) against the local AkkudoktorEOS repository.

The sandbox does not protect the repository from harmful changes by the agent.
It limits what a misled agent can reach on the machine, but the agent can still
write any change into the repository.

Primary security defence is to check every change before it is run on the host.
Same holds for opening a pull request or updating one.

Additional changes

- Reduce AGENTS.md to the project summary, baseline rules, completion checklist,
  and an index of the skills.
- Add skills for the Python environment and REST API error responses.
- Add the development guide page docs/develop/ai.md: the AI coding
  workflow, how agents get the project rules from AGENTS.md and ai/skills,
  and how to use the sandbox (start, agent logins, project commands with a
  virtual environment outside the workspace, running EOS and EOSdash,
  GitHub access, persistent data, security model).
- Add a checklist for reviewing agent changes before pushing, starting with
  .git, which stays writable in the sandbox.
- Check out all text files with LF line endings (.gitattributes), also on
  Windows with core.autocrlf, so the sandbox scripts run in the container
  and git in the container agrees with git on the host. Batch files keep CRLF.
- Publish the ports of ai/compose.yaml on request (AI_SANDBOX_PORTS=1).
  docker compose run publishes them only with --service-ports. Off by
  default, so that several sandboxes can run in parallel.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

ai/README.md

@@ -0,0 +1,81 @@
+# AkkudoktorEOS AI Development Sandbox
+
+Isolated Docker environment for AI-assisted development (OpenCode + Claude Code + Qwen Code)
+against the local AkkudoktorEOS repository.
+
+**The sandbox does not protect your repository from harmful changes by the agent.** It limits
+what a misled agent can reach on your machine, but the agent can still write any change into the
+repository. Check every change before you run it on the host, open a pull request or update one.
+See the security model in `docs/develop/ai.md`.
+
+## Layout
+
+- `compose.yaml` – service definition (bind-mounts the repo root to `/workspace`, with `ai/`
+  read-only)
+- `Dockerfile` – Debian slim + Python 3.13 + uv + Node.js + OpenCode + Claude Code + Qwen Code + gh,
+  with pinned versions
+- `entrypoint.sh` – container init (exec-bit stripping and reset of the shell startup files in
+  `$HOME`, warning about active git hooks, uv cache, git config, gh credential helper); installed
+  to `/usr/local/bin` in the image, outside the `ai-home` volume
+- `.env.example` – template, copied to `.env` on first run
+- `run.sh` / `run.ps1` / `run.bat` – entry points (prerequisite checks, sanity check of
+  `compose.yaml`, launch)
+- `skills/` – project rules for the agents, indexed in `AGENTS.md`
+
+## Usage
+
+From the repository root:
+
+- Linux/macOS: `chmod +x ai/run.sh && ./ai/run.sh`
+- Windows PowerShell: `.\ai\run.ps1`
+- Windows CMD: `ai\run.bat`
+
+Options (environment variables):
+
+- `AI_SANDBOX_REBUILD=1` – rebuild the image (e.g. after bumping the agent CLI versions in
+  `Dockerfile`)
+- `AI_SANDBOX_PORTS=1` – publish the ports of `compose.yaml` (8503 EOS, 8504 EOSdash) on
+  `127.0.0.1` of the host. Off by default, as only one sandbox at a time can publish them.
+  Start the servers with `--host 0.0.0.0` inside the container to make them reachable.
+- `AI_SANDBOX_SKILLS_RW=1` – make `ai/skills` writable in the sandbox, so the agent can update the
+  skills. The rest of `ai/` stays read-only.
+
+A command after `--` runs instead of the shell, e.g. `./ai/run.sh -- claude`. In PowerShell the
+`--` is optional: `.\ai\run.ps1 claude`. On Windows prefer PowerShell 7; `run.bat` cannot pass
+`!` and `%` to the container.
+
+On Windows the repository must be checked out with LF line endings, which `.gitattributes`
+enforces (see `docs/develop/ai.md`). In the sandbox, run `pre-commit` on the changed files only;
+`--all-files` fails on the read-only `ai/` directory. Changes to `ai/` itself (outside `ai/skills`,
+or to `ai/skills` without `AI_SANDBOX_SKILLS_RW=1`) must be checked on the host for the same reason.
+
+See `docs/develop/ai.md` for the AI coding workflow.
+
+Inside the container (working dir `/workspace`):
+
+```bash
+opencode auth login   # or /connect in the TUI
+claude                # then /login on first run
+qwen
+gh auth login         # then gh auth setup-git
+```
+
+All auth state persists in the `akkudoktor-ai-home` Docker volume. The local
+repository is bind-mounted at `/workspace`, so AI-made changes are visible on
+the host immediately.
+
+## Security notes
+
+- No `privileged` mode, no Docker socket, no host home mount, no `sudo`.
+- `ai/` (sandbox definition and launchers) is read-only in the container.
+- `.git` is writable, so the agent can commit. It can also plant git configuration and hooks that
+  run on the host (e.g. through `.git/commondir`). Check `.git` before you run any git command on
+  the host, see the review checklist in `docs/develop/ai.md`.
+- Git worktree checkouts are not supported: their `.git` is a file pointing outside the
+  repository, so git does not work in the sandbox.
+- Container user matches the host UID/GID (Linux/macOS) so file ownership is preserved.
+- Credentials are never written to git or to `compose.yaml`; they live only
+  in the persistent home volume via each tool's own login flow.
+- The home volume persists between sessions. Remove it (`docker volume rm akkudoktor-ai-home`)
+  if a session may have been misled.
+- The launchers' checks of `compose.yaml` are a sanity check, not a complete validation.