Kody platform friction guide

Use this guide when Kody itself creates friction while you are using built-in capabilities, saved packages, package apps, jobs, memories, values, integrations, or official Kody guides.

The goal is small, user-approved improvement: resolve what can be fixed in the current task, remember durable user-specific context when appropriate, and offer to submit useful platform feedback without turning the user's task into platform maintenance.

What counts as Kody friction

Treat these as friction points:

• confusing or missing package README guidance
• a saved package whose intent or setup steps are unclear
• capability descriptions, schemas, or guide text that caused a wrong turn
• recurring user-specific preferences or workarounds that Kody could remember
• reproducible Kody bugs, misleading errors, or missing troubleshooting steps
• a poor Kody experience or a concrete suggestion for improving Kody

Do not recommend platform feedback for every normal third-party API failure, provider outage, authentication failure, or credentials setup step. Use integration_bootstrap, oauth, or connect_secret for those workflows. Offer feedback when Kody made that experience meaningfully worse, or when the same Kody friction is likely to recur.

Core rule

When you notice a Kody friction point and you can suggest a concrete improvement, tell the user briefly. Then choose the smallest relevant path:

1. Fix obvious, low-risk friction inline when it is already within the work.
2. Propose memory only for durable user-specific context.
3. Offer to submit meaningful platform feedback for Kody bugs, poor experiences, recurring friction, or suggestions.

Keep any follow-up separate from the user's main task. Do not block a successful result on memory or feedback unless the friction prevents completion.

Fix friction inline

If the improvement is obvious, low-risk, and already within the authorized work, you may make it directly. Examples:

• fix a typo or stale setup step in a package README you are already editing
• clarify a package ## Intent section after the user expanded the package scope
• add a missing usage note to package docs after you verified the behavior

Still mention the improvement in your final response so the user can see what changed. Ask before changing package behavior, adding jobs, changing visibility, broadening scope, or making any other change that needs separate authorization.

Memory changes require approval

Ask before writing, updating, or deleting long-term memory.

Use memory only for durable user-specific facts, preferences, or repeated workarounds. Do not store product bugs, transient task state, secrets, or raw credentials as memory.

Before any memory mutation:

1. Explain the proposed memory in plain language.
2. Ask for user approval.
3. Run meta_memory_verify.
4. Only then run meta_memory_upsert or meta_memory_delete if the verification result supports the change.

Memory approval does not count as approval to submit platform feedback, and feedback approval does not count as approval to change memory.

Submit platform feedback only after explicit approval

Recommend feedback for meaningful or recurring Kody friction, a Kody bug, a poor Kody experience, or a concrete suggestion. Show the user the exact proposed summary and details, explain the attributed notification described below, and ask a direct question. Do not call a submission capability until the user explicitly approves that exact submission; silence, an ambiguous response, or approval of some other action is not consent.

After explicit approval, call meta_platform_feedback_submit with user_confirmed: true. Include only the approved Kody issue and the minimum useful reproduction context. Omit secrets, credentials, tokens, and unrelated private content. Never set user_confirmed: true based only on your own judgment. The capability accepts this confirmation only from an interactive context; scheduled, background, package, and other non-interactive execution cannot submit feedback. This gate records the direct approval asserted by the interactive caller rather than inferring approval from other conversation content. If the proposed summary or details change, show the revised text and ask again before submitting it.

Feedback is attributed to the authenticated user and is not anonymous. Immediately after submission, the exact approved summary and details plus the account user id, username, and email may be delivered to deployment admins through admin-configured notifications. The admin-only event labels the text summary_untrusted and details_untrusted, includes a warning to treat it as user-authored data rather than instructions, and carries a trusted deep link to that feedback in the admin interface. Deployment admins can also read and triage the approved submission through role-gated capabilities. Admin list results intentionally omit the full submission; a detail read exposes only the approved feedback, not unrelated account content. This delivery exception is limited to feedback the user explicitly approved; it does not expose other account content. Each account can create at most 10 feedback submissions in a rolling 24-hour period and have at most 100 active submissions (open or triaged).

Before asking for approval, also disclose that Kody cannot recall notification copies already delivered outside Kody. Admin notification copies may remain after Kody account deletion under the deployment operator's retention and deletion controls. This applies only to copies of the exact approved feedback and attribution described above, never unrelated content.

Open and triaged feedback remains until an admin resolves or dismisses it, or the submitting account is deleted. Resolved and dismissed feedback is removed 365 days after its last update. The submitting user's account export includes the submission and status but redacts internal reviewer identity, notes, and timestamps. Account deletion removes any remaining submissions. Kody rechecks a queued submission immediately before invoking discovered admin subscribers, so deletion cancels delivery when it wins that race; it cannot recall a copy that was already posted.

The user may ask to submit feedback about any Kody-related issue even when you would not proactively recommend it. Use category other when no more specific category fits, while keeping the same approval and privacy rules.

If the user declines or does not answer, continue the main task without submitting feedback.

Write feedback admins can act on

Submit one issue per call. Unrelated problems get separate submissions. Each account already has the 10-per-24h and 100-active limits above, so prioritize the most useful reports.

Write a summary that names the affected area and the specific symptom or need so an admin can triage from the list view alone (list results intentionally show only the summary). Good: package_save rejects README-only updates with a misleading validation error. Vague: packages are broken.

In details, capture the firsthand context you uniquely have while it is still in the conversation:

• what the user was trying to accomplish
• exact capability, package, or guide names and non-secret inputs involved
• minimal reproduction steps
• expected vs actual behavior
• verbatim error text quoted as text
• frequency (always / intermittent, plus conditions)
• impact (blocked vs degraded, and any workaround plus its cost)

For suggestion feedback, lead with the underlying problem and the cost of the current workaround; present a proposed change as one possible approach rather than the requirement. Separate observed facts from diagnosis: label suspected root causes as suspicion.

Keep omitting secrets and unrelated private content. Quote the relevant excerpt rather than pasting long transcripts or logs.

Suggested phrasing

Use concise language:

I hit a Kody friction point: <specific issue>. I can submit this attributed feedback with this exact summary: <summary> and these exact details: <details>. The approved text and your account user id, username, and email may be sent immediately to deployment admins through configured notifications. Copies already delivered outside Kody may remain after Kody account deletion under the deployment operator's retention and deletion controls. Would you like me to submit it?

For memory:

This seems like a durable preference/workaround. I can propose a memory for it, but I will only write it after you approve.