MeWeb/AGENT.md

# AGENT.md — operating contract for agents working on MeWeb

Read this first. **`PATTERNS.md` is canonical for how code is written** (cite "PATTERNS #n"); **`CLAUDE.md` is the
quick reference** (commands, map, pitfalls). When a tool in the repo enforces a rule (the compiler, `.editorconfig`,
`tools/lint.cs`), the tool is the source of truth.

## What MeWeb is

**“me-web?”** tells an ordinary person whether their own connection and device can host a server, and what stands in
the way: no public address (CGNAT), blocked ports, a firewall on the provider's router, a dynamic address, a mail
port closed, a residential blocklist. It runs every automatic check it can, draws the path from the device to the
provider, explains each finding in plain words, and works mostly offline from an embedded knowledge database.
Avalonia 12 on .NET 10 for Linux, Windows, macOS and Android (`src/MeWeb.App` + heads), a small server for the
checks that need a vantage point outside the user's network (`src/MeWeb.Server`, `meweb.arasaka.software`).
Free software under AGPL-3.0, published by Arasaka di Hvozdikov Yevheniy.

## Conventions that differ from defaults (full rulings in `PATTERNS.md`)

- **No comments in source** — none, of any kind (#42).
- **No `private`**, no `_` prefixes, **`Nullable` disabled**, **2-space indent**, **`var` everywhere** (#92).
- **Primary constructors**, `IOptionsMonitor<T>`, `CancellationToken` last and forwarded (#1, #87, #88).
- **Routes only in `src/MeWeb.Shared/Endpoints.cs`** (#9); DTOs are classes named `View*`, `Upsert*`, `*Form` (#34).
- **UI text:** resx keys only, sentence case, every language present, drafts labelled (#39, #50, #125).
- **Every outbound host is declared** in the app's "What this app contacts" screen (#120).

## Hard rules — DO NOT

1. **Never commit a secret.** This repository is public. The Android keystore, the update-feed key, Mongo
   credentials and blocklist keys live in Gitea Actions secrets or in `/etc/meweb/meweb.env` on the server, never in
   git, never in a log, never printed.
2. **Never regenerate or delete the Android signing key.** A new key stops every installed app from updating.
3. **Never run the release workflow on code from a pull request.** CI runs on the production box: only pushes to
   `master` and `v*` tags trigger it.
4. **Never `pkill -f` / `killall`.** Stop exactly the PID you started.
5. **Never create a branch, force-push or rewrite history** (#46).
6. **Never widen what the app contacts** without updating the declared list in the same change (#120).
7. **Never change a user's network without consent** (#122), and never point the probe at anything but the
   caller's own address (#123).
8. **Never recreate a test project.** Verification is the `/verify` ladder.

## Evidence

Report the evidence level honestly: **E1** code-traced, **E2** exercised here (build, curl, headless screenshots),
**E3** live on a real device or a real network. Never report E3 from an E2 check.

## Git policy

- Trunk only: `master`, remote `git.thepra.dev/Arasaka/MeWeb` (public).
- A `v<Version>` tag releases every platform and deploys the server; the tag must equal `Version` in
  `Directory.Build.props`.
- Stage explicit paths, review `git status` and `git diff --cached --stat` before committing.