docs(spark-http-proxy): document the certs topic and its deprecated names

[paolomainardi]

User description

🤖 This was written by an AI agent on behalf of @paolomainardi.

Refs sparkfabrik/http-proxy#160. Follows sparkfabrik/http-proxy#162, merged as b2de1c7, which grouped the certificate commands under spark-http-proxy certs. The skill described the three old names in 17 places across six files.

What changes

• references/certificates.md is rewritten around the topic: a command table, certs generate explained (it applies without a restart, which the old text got wrong), a new section on list, describe and delete with the real output shapes, and the wildcard gotcha now points at certs describe <hostname>, which names the wildcard that falls one label short and the one to generate.
• SKILL.md updates the decision table and the command table, tells the agent to run certs describe first on a certificate warning, and explains that a generate-mkcert is deprecated warning in a user's terminal is expected on an up-to-date CLI, not a broken install.
• provisioning.md, uninstall.md, troubleshooting.md, peer-routing.md rename their single mentions. The sjust system-install-mkcert sparkdock command stays as it is, and the pasteable line in peer-routing.md stays pasteable.
• CHANGELOG.md gets a dated entry.

Not changed

No evals/ exist for this skill, so nothing there to update. The hosts describe half of the upstream issue is not merged and stays out.

Verification

Prettier passes on every touched file. Every remaining mention of an old command name in the skill is in the sentence that explains the deprecation.

---

PR Type

Documentation

---

Description

• Document unified certs certificate command topic

• Add listing, inspection, and deletion guidance

• Correct generation to apply without restarts

• Explain deprecated command warnings and replacements

---

Diagram Walkthrough

flowchart LR
  warning["Certificate warning"]
  describe["certs describe"]
  diagnosis["Coverage diagnosis"]
  generate["certs generate"]
  proxy["Running proxy"]
  warning -- "inspect with" --> describe
  describe -- "provides" --> diagnosis
  diagnosis -- "recommends" --> generate
  generate -- "applies without restart" --> proxy

Loading

File Walkthrough

Relevant files

Documentation

7 files CHANGELOG.md Record certificate command documentation update                    +6/-0      SKILL.md Update certificate workflows and deprecated command guidance +34/-24  certificates.md Expand `certs` commands and troubleshooting reference        +81/-15  peer-routing.md Replace peer certificate generation command                            +1/-1      provisioning.md Update platform certificate generation references                +2/-2      troubleshooting.md Add certificate coverage diagnostics to troubleshooting    +3/-1      uninstall.md Rename automatic certificate setup command                              +1/-1

---

---

Assisted-by: pr-agent/gpt-5.6-sol

[sparkfabrik-ai-bot]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 160 - Partially compliant Compliant requirements: Explain local TLS termination for peer hostnames. Document spark-http-proxy certs generate on the reaching machine. Explain the single-label wildcard rule. Include the measured hostname examples. Include the CN=TRAEFIK DEFAULT CERT failure output. Record certificate guidance in the changelog. Non-compliant requirements: Add trigger cases for peer-hostname certificate warnings and TRAEFIK DEFAULT CERT; the skill's evaluation files have subsequently been removed. Requires further human verification: Confirm the documented certificate-selection examples still match the current proxy at runtime. 162 - PR Code Verified Compliant requirements: Use tailscale-peers [--refresh] in the command reference. Update peer-routing guidance to use --refresh. Document the PROXY and EXCLUDED report groups. Preserve individual exclusion statuses and fixes. Remove the unused skill evaluation files. Remove obsolete tailscale-refresh-peers expectations. Record the changes in the changelog. Requires further human verification: Confirm the documented grouped table still matches the output rendered by the current upstream proxy.

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Duplicate Date This inserts another 2026-09-01 section immediately before the existing section with the same date, splitting that date's changes across duplicate headings. Remove the new heading or consolidate the entries under a single dated section. ## [2026-09-01] ### Changed

---

Assisted-by: pr-agent/gpt-5.6-sol

[sparkfabrik-ai-bot]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Remove the duplicate changelog section Remove the newly inserted date heading because the diff already contains another 2026-09-01 section immediately below. Keeping both splits changes for the same date into duplicate sections and leaves the certificate entry attached to the preceding section. CHANGELOG.md [13-17] - `spark-http-proxy` skill: the certificate commands are documented as the `certs` topic (`list`, `describe`, `generate`, `delete`); `certs describe` is the first step on a certificate warning, and the deprecated `generate-mkcert`, `list-certs` and `remove-cert` warnings are explained as expected -## [2026-09-01] - -### Changed - Suggestion importance[1-10]: 5 __ Why: Removing the newly added duplicate 2026-09-01 heading avoids splitting same-date changes across adjacent sections. The proposed replacement accurately removes that heading while retaining the certificate changelog entry.	Low
	Diagnose certificate warnings before generation Make certs describe the initial action, consistent with the detailed guidance later in this file. Generating immediately may create an unnecessary certificate without diagnosing coverage, validity, or serving status. skills/system/spark-http-proxy/SKILL.md [59] -| Get trusted HTTPS / fix certificate warnings | Run `certs generate` | `references/certificates.md` | +| Get trusted HTTPS / fix certificate warnings | Run `certs describe <hostname>` | `references/certificates.md` | Suggestion importance[1-10]: 4 __ Why: This aligns the table with the later guidance that certs describe <hostname> should diagnose certificate warnings first. However, certs generate remains appropriate when the user simply wants to enable trusted HTTPS, so the combined row represents two slightly different workflows.	Low

---

Assisted-by: pr-agent/gpt-5.6-sol