📝 Add test-certificate-and-key convention to AGENTS.md

[AlexV525]

What

Add a "Test certificates and keys" subsection to AGENTS.md §3 (and the Chinese mirror AGENTS-ZH.md), placed after the "Extra scrutiny in security- and network-critical areas" subsection.

Why

Motivated by PR #2583, which introduced a committed self-signed test private key without false_secrets or .pubignore safeguards. The repo previously had no documented convention for this — the implicit "generate at test time" practice (see scripts/prepare_pinning_certs.sh) was not stated anywhere contributors or agents could find it.

Content

The new subsection covers:

1. Self-signed test keys are not real secrets — but committing them has costs (scanner noise, package bloat, convention inconsistency).
2. Prefer generating certificates at test setup over committing static files.
3. If static fixtures are unavoidable, exclude from the published package with both:
   • false_secrets in pubspec.yaml (suppresses pub leak-detection).
   • A .pubignore inside the fixture subdirectory — never at package root (a root .pubignore overrides the root .gitignore, silently re-including build artifacts).

The .pubignore placement warning is the non-obvious part — verified empirically that a root-level .pubignore causes build/ and other git-ignored files to leak into the published artifact.

---

Drafting by AlexV525, with research and writing assistance from GLM-5.2 via omp.

[CaiJingLong]

Review conclusion: Approve

Change summary

This PR adds a "Test certificates and keys" subsection to AGENTS.md §3 (English) and the corresponding AGENTS-ZH.md (Chinese), placed between "Extra scrutiny in security- and network-critical areas" and "Dependency changes". The new subsection documents the repo convention for handling self-signed test certificates/keys: prefer generating at test setup, and if static fixtures are unavoidable, exclude them from published artifacts via false_secrets + a subdirectory-level .pubignore.

Review details

Dimension	Conclusion	Notes
Correctness	Pass	All factual claims verified against official dart.dev docs. false_secrets is a real pubspec field (added Dart 2.15) that suppresses pub's pre-publish leak detection. The .pubignore placement warning is accurate — dart.dev publishing docs confirm "If a directory contains both a .pubignore file and a .gitignore file, then dart pub publish ignores that directory's .gitignore file", so a root .pubignore would indeed override the root .gitignore for the entire package. The referenced scripts/prepare_pinning_certs.sh exists and generates pinning fingerprints at test time via openssl s_client, consistent with the "generate at test time" convention described.
Tests	N/A	Documentation-only change; no code logic to test.
Style	Pass	Writing tone and formatting match existing AGENTS.md conventions. English and Chinese versions are semantically equivalent. Commit message uses gitmoji 📝 with capitalized subject — correct per §8.2. Branch name docs/test-key-convention follows category/short-description convention per §8.1.
Risk	Pass	No code changes — zero regression, security, performance, or compatibility risk. The documentation itself promotes security best practices for test certificate handling.
Documentation	Pass	This PR IS the documentation change. No CHANGELOG entry needed — AGENTS.md/AGENTS-ZH.md are repo-level contributor guidelines, not a published package. No public API changes.
Repo constraints	Pass	AI attribution properly disclosed: commit includes Co-Authored-By: GLM-5.2 <noreply@zhipu.ai>, PR description states "research and writing assistance from GLM-5.2 via omp". One PR, one concern — clean scope. Motivation is traceable to PR #2583.

Suggestions (non-blocking)

• The PR body replaces the PR template checklist entirely rather than marking non-applicable items. For a docs-only PR most items don't apply, but per §8.6 the convention is to keep the checklist and annotate non-applicable items with (not applicable — reason). Consider this for future PRs; not worth a force-push for this one.

Confirmed key points

• Correctness: All external claims (false_secrets field, .pubignore override behavior, scripts/prepare_pinning_certs.sh existence) verified against dart.dev official documentation and repo source.
• Tests: N/A — pure documentation change, no logic to test.
• Risk: Zero code changes; no regression, security, or compatibility risk.

---

This review was generated by AI agent omp (model: glm-5-2).