Principles for agent-facing Portal changes

[gosunuts]

Summary

Bar for agent-facing Portal changes. Other issues should say whether they fit this issue, with a comment that references it.

Principles

1. AI-usable. The change makes a real agent path shorter or less ambiguous: named fields over concatenated URLs, visible errors at the CLI's log level, hostnames that match the cert the agent will present. Local-harness-only fixes are allowed, but they are not the same as the production expose recipe.

2. Access surface, not core semantics. Prefer changes at the interface boundary: CLI, logs, config, skills, docs, installer/service integration, local harnesses, and additive API fields. Do not change protocol, identity, trust, payment, discovery, or transport semantics merely to make an agent workflow easier. Do not add a Portal-plugin workflow engine, finding store, approval DB, or feedback CLI. That stays outside this repo (see Rethink Portal feedback automation as an external workflow #331). Do not fork protocol, payment, identity, or discovery into a second implementation.

3. Compatibility. Additive logs and more-permissive local defaults are fine. Do not change production relay URLs, public listen addresses, or tenant hostnames without calling that out. Client and relay must ship together when a hostname or listen default changes.

4. One mechanism, one patch. Small PRs. No parallel helpers for the same contract. No extra abstraction that exists only to look general. A second patch that restates an already-open mechanism is a comment, not a new issue. Prefer deleting skill instructions over adding new ones: if a skill accumulates repeated exceptions, parsing rules, or workaround text, fix the Portal surface and remove the instruction instead.

How to apply

On each candidate issue, comment with:

• Fit / partial / does not fit
• Which principles apply
• One line of evidence

Close or re-scope anything that fails 2 or 3. Keep 1 and 4 as the merge filter.

[gosunuts]

Map of the agent-facing batch against this bar. Closed work is grouped so the board is not a pile of siblings.

Production expose recipe (keep):

• Expose readiness is ambiguous with relay URL logs for agents and automation #326 / fix(sdk): emit public_url on HTTP service ready #335 — named public_url on HTTP ready
• Explicit --relays retries forever at debug so agents see neither ready nor error #338 / fix(sdk): warn on first explicit-relay retry #339 — first explicit---relays failure visible at warn

Local-relay harness (landed, not the public recipe):

• Loopback http --portal-url never reaches localhost dev certificates #336 / fix(utils): accept loopback http relay URLs #337 — loopback http:// portal-url
• Loopback IP portal-url issues tenant hostnames the local dev cert does not cover #340 / fix(utils): use localhost for loopback lease hostnames #341 — loopback lease hostname → .localhost
• Unknown SNI hostname closes the connection with no log #342 / fix(portal): log unknown public SNI hostnames #343 — unknown SNI hostname warn

Not doing:

• Loopback portal-url still listens on all interfaces #344 / fix(portal): bind loopback portal-url on 127.0.0.1 #345 — bind loopback portal-url on 127.0.0.1 only (closed)

Already the boundary, not this batch:

• Rethink Portal feedback automation as an external workflow #331 — no plugin workflow engine / finding store
• Add CONTRIBUTING.md with an AI accessibility contribution policy #327 — CONTRIBUTING / AI accessibility docs (orthogonal to the expose CLI)

New agent-facing issues should comment Fit/partial here before opening a sibling.

[gosunuts]

Fit. Principles 1 (AI-usable) and 2 (CLI access surface). Evidence: cold portal expose --help had no Flags section while -identity-path was already registered. Sibling: #351.