Skip to content

docs: rewrite the README — status first, then modes, api and the empty-answer diagnosis - #4

Open
Rethinger wants to merge 1 commit into
masterfrom
docs/readme-status-and-diagnosis
Open

Rethinger wants to merge 1 commit into
masterfrom
docs/readme-status-and-diagnosis

Conversation

@Rethinger

Copy link
Copy Markdown
Owner

what

rewrites the README. the old one read as a way around a limit — "the mode that
works", "exactly the free-tier bypass" — which is neither a fair description of
the tool nor useful documentation, and it left the most common failure
undocumented: an answer that comes back empty.

changes

  • status first. a section that says plainly that nothing here is authorized
    by opencode or opencode.ai, that the free tier is a lease on the running
    client, that refusals by egress reputation are the normal failure mode, and
    what happens on the wire (the proxy forwards your client's own requests; TLS
    is terminated locally with a CA in the data dir; no fingerprint is forged).
  • the client daemon's env, all three variables, with what each missing one
    looks like symptom by symptom: no proxy → 403 FreeTierError on every
    session; proxy without NO_PROXY → getaddrinfo ETIMEOUT in the client and
    tls handshake opencode.ai: EOF in the proxy log; NODE_EXTRA_CA_CERTS not
    pointing at ca.pem → nothing reaches the proxy at all.
  • "when an answer comes back empty" — the checklist for 200 + empty
    content + finish_reason: "error": serve's startup line, the daemon's
    /proc/<pid>/environ, the proxy log, the client's own log (Failed to drain Session), lanes status and proof.jsonl. that answer is the client's own
    session being refused upstream, not the gateway failing.
  • every operational fact is kept: flags, config keys, endpoints, models,
    streaming and usage semantics, auth, limits, lanes, harness yaml, deploy, and
    the reverse-engineering notes.

no code changes; go test ./... unaffected.

…y-answer diagnosis

the tone was doing the opposite of the job: it read as a way around a limit rather than as a gateway with a known, documented failure mode. dropped the bypass framing, kept every operational fact (flags, config keys, endpoints, limits, lanes, harness yaml, deploy, reverse-engineering notes).

new: a status section that says plainly that nothing here is authorized by the provider, that the free tier is a lease on the running client, and that refusals by egress reputation are the normal failure mode; the client daemon's env with what each missing variable looks like symptom by symptom; and a troubleshooting section for the 200-with-empty-content/ finish_reason=error answer, which is the client's own session being refused, not the gateway failing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant