@sunerpy/kiro-provider 0.7.0 → 0.8.1

package/README.md

@@ -23,6 +23,7 @@
 - [Use with Zuno](#use-with-zuno)
 - [Use with Codex CLI](#use-with-codex-cli)
 - [Use with Claude Code](#use-with-claude-code)
+- [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [License](#license)
 
@@ -563,8 +564,10 @@ Standard clients must also stay within the verified subset. In safe mode a
 client that always sends system/developer instructions, custom grammars,
 namespace tools, or Anthropic `cache_control` receives a field-level 400; the
 gateway does not modify that request to force it through Kiro. The optional
-`legacy-user-prefix` projection is a temporary instruction-only migration aid
-for v0.5.x/v0.6.x and is scheduled for removal in v0.7.0.
+`legacy-user-prefix` projection is an explicit instruction-only compatibility
+mode. It remains deprecated, but removal is evidence-gated: Kiro must expose a
+protocol-faithful native instruction channel, or affected clients must migrate
+away from instruction roles first.
 
 The default `session_affinity_mode: "explicit-only"` never hashes prompt text
 to guess a conversation. Responses checks, in order,
@@ -664,7 +667,8 @@ returns `unsupported_instruction_projection` and never rewrites the request.
 Set Zuno `options.maxTokens` to `null` as shown so its generic layer does not
 add the unsupported `max_output_tokens: 32000`. Neither setting uses a private
 Header or client-side prompt patch; the legacy mode is an explicit migration
-exception scheduled for removal in v0.7.0.
+exception whose removal is gated on native instruction fidelity or completed
+client migration.
 
 ## Use with Codex CLI
 
@@ -734,6 +738,20 @@ The preceding protocol/client matrix is retained in
 The older [`docs/E2E_VALIDATION_2026-08-22.md`](docs/E2E_VALIDATION_2026-08-22.md)
 is retained as historical v0.4 evidence only.
 
+## Troubleshooting
+
+[`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) is the symptom-first
+runbook: for each symptom it names the audit event, the
+`accounts list --details` availability value, or the HTTP status and
+`error.code` to look at, then the cause and the remedy. It covers
+`needs-relogin` and token-refresh failures, `quota-exhausted` versus
+`overage-blocked` (`stop_on_overage`), `503 no_healthy_accounts`, the
+`502 upstream_stream_*` codes with the pre-publication retry events, how to
+read `sdk_stream_terminal` when "the assistant announced a next step and
+stopped", reasoning-replay `400`s, the single-instance lock, configuration
+warnings, `413` variants, and proxy failures. It also lists `journalctl` grep
+recipes for the systemd service and the opt-in `request_shape` debug event.
+
 ## Development
 
 ```bash