@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/guides/send-feedback.md

@@ -0,0 +1,135 @@
+# Send Feedback To AgentKit
+
+## Goal
+
+Create a redacted local feedback draft when AgentKit itself is confusing, missing docs, or failing, then send it to AgentKit Cloud only after the user has authenticated.
+
+## When To Use This
+
+Use this for AgentKit product feedback, not for the user's agent's client conversations.
+
+Good cases:
+
+- an AgentKit CLI command failed and the error did not explain recovery;
+- a docs guide or generated skill is missing a step;
+- deploy, channel, provider, eval, or runtime behavior looks like an AgentKit bug;
+- the user's coding agent found a feature gap in AgentKit itself.
+
+Do not use this to upload private client data, provider keys, `.env` values, or full conversation transcripts.
+
+## Commands
+
+Create a local draft only:
+
+```sh
+agentkit feedback create --about last-run --kind bug --summary "Deploy failed after secrets sync"
+```
+
+Preview a draft:
+
+```sh
+agentkit feedback preview .agentkit/feedback/<draft>.json
+```
+
+Send a saved draft:
+
+```sh
+agentkit login --token agk_user_...
+agentkit feedback send .agentkit/feedback/<draft>.json
+```
+
+Create and send in one command:
+
+```sh
+agentkit feedback send --about deploy --kind deploy_issue --summary "Deploy doctor passed but deploy failed" --message "The recovery step was unclear."
+```
+
+## Files Created Or Edited
+
+`feedback create` writes ignored local files:
+
+```txt
+.agentkit/feedback/<timestamp>-<summary>.json
+.agentkit/feedback/<timestamp>-<summary>.md
+```
+
+These files are local diagnostic drafts. Keep `.agentkit/` out of commits.
+
+## Minimal Working Example
+
+```sh
+agentkit feedback create \
+  --about last-run \
+  --kind missing_docs \
+  --summary "The channel debug guide did not explain Discord bot mode recovery" \
+  --message "The command failed after setup, and I could not tell whether to rerun connect or setup."
+```
+
+Review the printed JSON path, then send it:
+
+```sh
+agentkit feedback send .agentkit/feedback/<draft>.json
+```
+
+## Safety Rules
+
+- Creating a draft never sends network feedback.
+- Sending requires AgentKit Cloud login.
+- The CLI redacts common bearer tokens, AgentKit tokens, provider key patterns, and Authorization headers before saving or sending.
+- AgentKit Cloud validates the payload again and stores the redacted report under the authenticated account.
+- Do not paste `.env` contents, provider key values, OAuth tokens, cookies, client PII, or full private transcripts into `--message`.
+- The feedback command does not upload arbitrary files and does not ask AgentKit Cloud to fetch URLs.
+- The deployed agent runtime does not send feedback to the AgentKit team.
+
+## Verification
+
+After creating a draft:
+
+```sh
+agentkit feedback preview .agentkit/feedback/<draft>.json
+```
+
+Expected:
+
+- `schema_version` is `agentkit.feedback.v1`;
+- `source.channel` is `cli`;
+- `context` describes the current capsule and deploy shape;
+- no secret values are present.
+
+After sending:
+
+```txt
+Feedback sent
+ID:     fb_...
+Status: new
+```
+
+## Troubleshooting
+
+`auth_required`:
+
+Log in before sending:
+
+```sh
+agentkit login --token agk_user_...
+```
+
+`feedback_draft_invalid`:
+
+Recreate the draft with `agentkit feedback create`. Do not hand-edit the JSON schema unless you keep `schema_version: "agentkit.feedback.v1"`.
+
+`payload_too_large`:
+
+Shorten `--message`. Do not paste full logs; include the command, exact error code, and the smallest useful excerpt.
+
+## Backend Contracts Used
+
+Feedback submit uses authenticated AgentKit Cloud account auth:
+
+```txt
+POST /v1/feedback
+Authorization: Bearer agk_user_...
+Idempotency-Key: fbdraft_...
+```
+
+The endpoint accepts only structured JSON feedback and stores it in the AgentKit Cloud feedback inbox.

package/docs/guides/use-provider.md

@@ -6,7 +6,9 @@ Switch a capsule from the offline `test/fake` provider to a Pi-backed provider.
 
 ## When To Use This
 
-Use this when local fake responses are no longer enough and the agent needs model behavior from OpenAI, Anthropic, or OpenRouter.
+Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, or another supported provider.
+
+The coding agent should not choose a real provider automatically. Ask the owner which provider to use, then update the capsule.
 
 ## Commands
 
@@ -19,6 +21,14 @@ npm run chat -- --message "hello"
 npm run agentkit -- inspect
 ```
 
+On Windows PowerShell, if `npm.ps1` is blocked by `PSSecurityException`, use the Windows command shim:
+
+```sh
+npm.cmd run typecheck
+npm.cmd run chat -- --message "hello"
+npm.cmd run agentkit -- inspect
+```
+
 ## Files Created Or Edited
 
 Edit:
@@ -75,6 +85,19 @@ provider: {
 secrets: ["OPENROUTER_API_KEY"],
 ```
 
+Prefer model ids or aliases listed by the installed Pi SDK when available, such as `~google/gemini-flash-latest`. If an OpenRouter model id is newer than the Pi model registry, AgentKit passes the id through to OpenRouter using Pi's OpenAI-compatible transport with conservative unknown-model metadata. The provider may still reject the request if the id is invalid, inaccessible, or does not support the tools/features the agent uses.
+
+## UI Verification
+
+After the provider is configured and the local secret is set, test through chat and UI:
+
+```sh
+npm run chat -- --message "hello"
+npm run dev
+```
+
+Open the printed `Chat:` URL and tell the owner the exact URL. If the provider is still `test/fake`, say the UI was tested only with the deterministic fake provider.
+
 ## Safety Rules
 
 - Keep `.env` local.
@@ -84,6 +107,7 @@ secrets: ["OPENROUTER_API_KEY"],
 - Do not import provider SDKs in the Agent Capsule.
 - AgentKit uses Pi SDK internally.
 - Run `agentkit inspect` to confirm secret status without printing values.
+- Do not claim real conversation behavior was tested until a real provider selected by the owner is configured.
 
 ## Verification
 
@@ -111,7 +135,7 @@ npm run agentkit -- inspect
 
 `provider_model_unsupported`:
 
-Use a model id known to the installed Pi SDK for that provider.
+For OpenAI or Anthropic, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
 
 Provider returns auth failure:
 
@@ -123,4 +147,4 @@ Check the key value, provider account status, and model access.
 
 ## Backend Contracts Used
 
-Local provider keys come from ignored `.env`, loaded directly by AgentKit. Hosted production will use `agentkit secret set <NAME>` and the secret API. Secret values have no readback in hosted responses.
+Local provider keys come from ignored `.env`, loaded directly by AgentKit. Hosted production uses `agentkit secret set <NAME> --from-local-env`, `--from-env`, or `--stdin` and the secret API. Secret values have no readback in hosted responses.