docs(spark-http-proxy): describe the live hosts describe

[paolomainardi]

User description

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

Refs sparkfabrik/http-proxy#164. Follows sparkfabrik/http-proxy#166, merged as d7947f4, which made hosts describe read the container live.

What changes

• SKILL.md updates the command-table row and the "What is served" section: hosts describe now answers "what is this container" (image, status and uptime, routed port and backend, network, reachability through the proxy, mounts, command). It tells the agent that command-line secrets are redacted by name and never by the shape of a value, so the output may still carry a secret before pasting, that a reachable other than 200 with a backend present points at the app rather than the proxy, and that a gone container is reported as not found.
• CHANGELOG.md gets a dated entry.

Verification

Prettier passes on both files. No evals/ exist for this skill.

---

PR Type

Documentation

---

Description

• Document live container inspection via hosts describe

• Explain routing, reachability, and stale records

• Warn command output may retain secrets

• Record behavior in dated changelog

---

Diagram Walkthrough

flowchart LR
  query["Hostname query"]
  describe["spark-http-proxy hosts describe"]
  docker["Live Docker container details"]
  proxy["Routing and reachability details"]
  query -- "requests inspection" --> describe
  describe -- "reads container" --> docker
  describe -- "checks routing" --> proxy

Loading

File Walkthrough

Relevant files

Documentation

CHANGELOG.md Record live hosts inspection documentation                              CHANGELOG.md Add a dated spark-http-proxy documentation entry Summarize live details reported by hosts describe +6/-0      SKILL.md Explain live container inspection with hosts describe        skills/system/spark-http-proxy/SKILL.md Describe live Docker and proxy inspection Explain routing, reachability, and stale records Document command redaction limitations and secret risks Clarify local and peer directory visibility +14/-5

---

---

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 ✅ 164 - PR Code Verified Compliant requirements: Add hosts [describe <hostname>] to the SKILL.md command table. Add a section explaining how to discover what is served and where it runs. Recommend using hosts before manually inspecting Docker. Clarify that directories are available only for local containers and are omitted for peers. Place the discovery guidance before the peer-routing section. Leave references/peer-routing.md unchanged. Do not add evals/ changes. Requires further human verification: Verify that the supporting CLI release is available before merging. 166 - PR Code Verified Compliant requirements: Update the command table to state that hosts describe reads a container live. Document image, status and uptime, routed port and backend, networks, proxy reachability, mounts, and command details. Explain that command secrets are redacted by name or URL userinfo, not by value shape, and warn that output may still contain secrets. Explain that non-200 reachability with a backend present indicates an application response rather than a proxy-routing failure. Explain that a removed container is reported as not found. Add a dated changelog entry. Do not add evals/ changes. Requires further human verification: Verify that Prettier passes for both modified files.

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Future Date The changelog entry is dated 2026-09-02, but the PR date is 2026-09-01. If merged today, the change will be grouped under a future date and make the chronological history inaccurate; use the actual merge date. ## [2026-09-02]

---

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

[sparkfabrik-ai-bot]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Avoid misdiagnosing non-success responses A non-200 response can still be generated by the proxy—for example, a gateway error—even when backend is present. Avoid directing operators exclusively toward the application; tell them to inspect the response and relevant logs before assigning the fault. skills/system/spark-http-proxy/SKILL.md [211-212] -A `reachable` other than `200` with a `backend` present points at the app, not -the proxy. +A `reachable` result other than `200` can come from either the proxy or the +application, even when a `backend` is present; inspect the response and the +proxy and application logs before assigning the failure. Suggestion importance[1-10]: 6 __ Why: A configured backend does not rule out proxy-generated errors such as gateway failures. The revision prevents misleading operational guidance and accurately reflects the proposed change.	Low

---

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