stack: Telemetrie-Default nach Installationsform, Byte-Deckel und Session-Retention (schliesst #55)

Files changed:
- .gitea/workflows/ci.yml
- .gitignore
- CHANGES.md
- EVALS.md
- INSTALL-MCP.md
- INSTALL.md
- VERSION
- instructions/setup-instance.md
- reports/CONTRACT.md
- tools/CONTRACT.md
- tools/chemenu/commands/doctor.py
- tools/chemenu/config.py
- tools/chemenu/mcp/server.py
- tools/chemenu/telemetry/policy.py
- tools/chemenu/telemetry/schema.py
- tools/chemenu/telemetry/writer.py
- tools/chemenu/tests/conftest.py
- tools/chemenu/tests/test_doctor.py
- tools/chemenu/tests/test_mcp_server.py
- tools/chemenu/tests/test_telemetry_emit.py
- tools/chemenu/tests/test_telemetry_policy.py
- tools/chemenu/version.py

EVALS.md

@@ -190,6 +190,57 @@ What that verification turned up, and what it changes:
   `wikitool instructions sync` publishes is a project-scope skill source for Vibe, so this
   repository needs no adaptation to be worked on with it - only a trusted folder.
 
+## Whether it runs at all
+
+The default depends on how this tree got here, not on a single hard-coded switch -
+[tools/chemenu/telemetry/policy.py](tools/chemenu/telemetry/policy.py) is the one place that
+resolves it, so `wikitool doctor`, the writer and the MCP server's start-up guard all answer the
+same question the same way:
+
+| Installation form | Default | Marker |
+|---|---|---|
+| Git clone of this repo (dev checkout) | **on** (opt-out) | No `.wikitool-release.json` |
+| `dist export` tarball (a distributed instance) | **off** (opt-in) | `.wikitool-release.json` present |
+
+The form is read off `.wikitool-release.json`, the same stamp `version check` and `dist upgrade`
+already use to tell a distribution from the repo it came from - present means an operator never
+asked for telemetry, absent means this is the dev checkout the stack ships from, where the traces
+are its own measuring instrument (the rest of this file). A private instance
+(`instructions/private-instance.md`) is a git clone of an *export*, so it carries the stamp and
+defaults off too - it is a consuming instance, not a measuring stand.
+
+**Turning it on for a distributed instance** is a per-checkout `.wikitool-telemetry.json` at the
+repo root, gitignored like `.wikitool-remotes.json` and for the same reason: the consent to write
+cleartext prompts to *this* disk belongs to the checkout, not the corpus, so a second clone must
+not inherit it silently. `instructions/setup-instance.md`'s Telemetry decision point asks for it
+during setup; nothing writes it automatically.
+
+```json
+{ "enabled": true, "max_session_bytes": 5242880, "keep_sessions": 250 }
+```
+
+All three keys are optional. `WIKI_TRACE` still overrides `enabled` in both directions and beats
+the file, exactly as it always has.
+
+**Two independent quantity caps, both enforced fail-silent in `emit()`** - never in
+`write_event()`, which the test suite calls directly to exercise the format without the policy
+wrapped around it:
+
+- **A byte cap per session trace** (default 5 MiB, `max_session_bytes` / `WIKI_TRACE_MAX_SESSION_BYTES`),
+  checked with one `stat` before every append. Once a trace is at or over the cap, further calls
+  in that session write nothing except a single `telemetry.limit` event - elected by the same
+  single-writer trick `session.start` uses (an exclusive-create on a `.limit` marker file), so a
+  trace that was cut off is distinguishable from one whose writer simply crashed.
+- **Retention by session count** (default 250, `keep_sessions` / `WIKI_TRACE_KEEP_SESSIONS`),
+  applied once, right before a brand-new session directory is created - never per event, and
+  never against the session doing the creating. It deletes exactly `trace.jsonl` and `.limit`
+  from the oldest directories beyond the cap and only `rmdir`s one once it is empty; nothing
+  under `reports/` is ever removed in bulk.
+
+The default of 250 is chosen above what this repo's own checkout has accumulated as of
+2026-09-10 (231 session directories, well under 400 KiB total) - the cap starts biting on future
+growth, not on the existing history.
+
 ## What never reaches a trace
 
 Prompts and assistant replies **are** recorded in cleartext, locally. A failure taxonomy
@@ -214,10 +265,12 @@ may only be enabled against a collector you run yourself.
 
 | Variable | Effect |
 |---|---|
-| `WIKI_TRACE=0` | Record nothing |
+| `WIKI_TRACE` | `0`/`1` overrides on/off in either direction, beating both the installation-form default and `.wikitool-telemetry.json` - see § Whether it runs at all |
 | `WIKI_TRACE_DIR` | Write traces somewhere other than `reports/telemetry/` |
 | `WIKI_TRACE_CONTENT=0` | Lengths and digests instead of text |
 | `WIKI_TRACE_MAX_CONTENT` | Per-attribute cap in characters |
+| `WIKI_TRACE_MAX_SESSION_BYTES` | Per-session trace byte cap (default 5 MiB) - overrides `.wikitool-telemetry.json`'s `max_session_bytes` |
+| `WIKI_TRACE_KEEP_SESSIONS` | How many session directories retention keeps (default 250) - overrides `.wikitool-telemetry.json`'s `keep_sessions` |
 | `WIKITOOL_SESSION_ID` | The join key, and the directory a trace lands in |
 
 ## Evaluation levels