# Where agent guidance lives

Agents keep stuffing specifics into the wrong layer: MCP server instructions,
memories, package docs, or export JSDoc. Put guidance at the **lowest layer that
still reaches the agents who need it**, and keep higher layers thin. This page
is the decision guide.

Before you call `metaMemoryUpsert` or `metaSetMcpServerInstructions`, open this
guide (`search({ entity: "guide:agent_guidance" })` or `/docs/agent-guidance`).
If the fact is package- or export-scoped, edit the package instead.

## The four layers

| Layer                                                                                                        | Reaches                                                       | Put here                                                                                                               | Do not put here                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP server instructions** (short built-in stub + optional user overlay via `metaSetMcpServerInstructions`) | Every conversation on new MCP sessions                        | Short, general nudges: start with `search`, verify-first memory, pointers to docs / local CLI                          | Package inventory, export gotchas, account-specific durable facts, long runbooks, prefer-over-host policy                                 |
| **Package documentation** (`README.md` human / `AGENTS.md` agent)                                            | Agents (and people) working on or invoking that package       | Intent, how pieces fit, workflows, staging or upload steps, smoke tests, edge cases that apply to the whole package    | Account-wide personal facts, which cloud account owns what, one-export call limits that belong on that export                             |
| **JSDoc on exports**                                                                                         | Agents reading search Purpose / entity detail for that export | Call shape specifics, limits, when to pick this export over a sibling                                                  | Package-wide workflows, durable user facts, always-on session policy                                                                      |
| **Memories**                                                                                                 | Agents acting as you (personal org), any connection org       | Personal facts without a better home: identifiers, relationships, preferences. Ask before copying into an org package. | Shared org knowledge (use package docs / org instructions), repeatable behavior, task defaults, credentials (use [secrets](/docs/secrets)) |

Higher layers appear more often and cost more context. Lower layers stay close
to the code or fact they describe. Prefer the lowest layer that still works.

## Decision checklist

Prefer code that handles a requirement automatically over an instruction the
agent must remember. For example, build quoting into a reply utility and put the
default location in the weather utility’s documented configuration.

Ask in order:

1. **Is this about one export?** Put it in that export's JSDoc. Search Purpose
   comes from JSDoc
   ([Package authoring — Export JSDoc](/docs/package-authoring#export-jsdoc)).
2. **Is this about one package's intent, workflow, or agent runbook?** Put it in
   `README.md` and/or `AGENTS.md`
   ([Package authoring — Package docs](/docs/package-authoring#package-docs-readme.md-agents.md)).
3. **Is this a durable fact about the person or account, not about a package?**
   Put it in [memory](/docs/memory) (`metaMemoryVerify` then `metaMemoryUpsert`).
4. **Is this rare always-on session policy that every conversation must see?**
   Only then consider the MCP overlay (`metaGetMcpServerInstructions` /
   `metaSetMcpServerInstructions`). Prefer memories for account-wide personal
   facts; keep the overlay short. The built-in stub already covers search-first
   and local CLI pointers.

If step 1 or 2 applies, do **not** upsert a memory and do **not** extend the MCP
overlay. Update the package.

## Concrete examples (generic)

**MCP server instructions (good):** "When blocked on credentials or access,
`search` Kody for waiting state and the relevant integration or secret docs."

**MCP server instructions (bad):** Listing every package the account uses, or
copying an export's JSON-only body limit into the overlay.

**Package docs (good):** How to stage an upload, which files to touch for a
common workflow, smoke-test calls for the package as a whole.

**Package docs (bad):** "This user's Cloudflare account id is …" or "always
prefer JSON over binary for export X" when only that export has the limit.

**Export JSDoc (good):** "Accepts a JSON body only; for raw binary use `fetch`
against the returned URL." Or "Call this when you need a preview; use `commit`
when ready to publish."

**Export JSDoc (bad):** Repeating the whole package Intent, or storing the
user's preferred timezone.

**Memory (good):** Project nicknames, handles and ids not recorded elsewhere,
personal preferences, which of _your_ cloud accounts you use for what.

**Memory (bad):** "Package foo's upload flow is …", "Export bar rejects binary
bodies," or org-wide facts teammates should share. Those belong in package docs,
JSDoc, or org instructions — ask before copying a personal memory into an org
package.

## Built-in MCP instructions and the user overlay

Every MCP session gets a short neutral built-in stub (what Kody is, how to use
`search` / `execute`, and a pointer to local CLI via `guide:local_execute`). It
does not list packages, domains, or lifecycle runbooks — discover those with
`search`.

The optional overlay from `metaSetMcpServerInstructions` appends to that stub
for **new** sessions. Use it only for rare always-on session policy. Prefer
[memories](/docs/memory) for account-wide personal facts; put repeatable behavior
and defaults in packages with typed inputs and documented defaults. Overlay
updates do not rewrite a host that already cached server instructions; reconnect
if needed.

## Writing guidance: do this first

1. Open `guide:agent_guidance` (this page) when unsure which layer fits.
2. If the candidate is package- or export-scoped, edit `README.md` / `AGENTS.md`
   or export JSDoc, then publish. Skip memory upsert and MCP overlay set.
3. If it is an account-level durable fact, run `metaMemoryVerify`, then upsert
   only after review ([Shared memory](/docs/memory)).
4. If it is rare session policy, read the current overlay with
   `metaGetMcpServerInstructions`, keep it short, and set only what must appear
   in every conversation.

## Where to go next

- [Shared memory](/docs/memory) — what belongs in memory and the verify-first
  write path.
- [Package authoring](/docs/package-authoring) — README / AGENTS.md, Export
  JSDoc, and runtime input checking for agent-facing exports.
- [Search and execute](/docs/search-and-execute) — how agents discover guides and
  package detail.
- [Local CLI execute](/docs/local-execute) (`guide:local_execute`) and the
  [prefer-local-cli-execute](https://raw.githubusercontent.com/kody-hq/kody/main/.agents/skills/prefer-local-cli-execute/SKILL.md)
  skill.
- [Open API](/docs/open-api) — HTTPS Open API and MCP `api` (`guide:open_api`).
- [Packages, integrations, and MCP servers](/docs/packages-integrations-mcp) —
  keep those three surfaces from collapsing into each other.