docs: add best practices for server and client implementors

[tadasant]

What

Adds docs/best-practices.md — advisory guidance for the two sides of the Server Card ecosystem — and links it from the README. Docs-only; no schema or code changes.

Server Implementors

Recommends serving a Server Card for any remote MCP server, framed as the server's connection entry point (advertises transport endpoints, protocol versions, and a hint at incoming requirements like auth, before initialization). Notes the card is valuable on its own even without a catalog (a client that already knows your URL can point at it directly), that it's advisory and MUST NOT be treated as authoritative for access control, that non-remote servers belong in the MCP Registry's server.json instead, that internal-but-remote servers should still serve a card, and that you should also list it in an AI Catalog entry on the domain people associate with your service. Links the pending auth-scenarios (#13) and tool-metadata (#30) discussions.

Client Implementors

Frames in-session discovery as a spectrum of integration points rather than prescribing one approach — explicitly "do what fits your client." All examples are grounded in Goose, Block's open-source MCP agent (whose extensions are themselves MCP servers), and verified against the live docs:

• Watch outbound traffic at the egress boundary — the comprehensive end: if a client already mediates network access (Goose's seatbelt sandbox forces all outbound traffic through a local proxy that checks each destination against blocked.txt), discovery can ride the same seam — probe new destination domains in the background and cache domain → catalog.
• Probe on a deliberate fetch — a PreToolUse lifecycle hook matched to a web-fetch tool reads the target URL and probes that host.
• Probe the domains a project already points at — URLs in .goosehints / AGENTS.md / a recipe, probed once per session via SessionStart / UserPromptSubmit.
• Offer a hit as a one-click extension install — an AI Catalog entry maps onto Goose's existing goose://extension?...&type=streamable_http deep link (or a config.yaml block); installs mid-turn, making clear which domain.
• Gate the install behind the permission model the user already knows — reuse Goose's permission modes / always-allow / ask-before / never-allow.
• Keep probing cheap, and let enterprises scope it — async, cache misses, honor Cache-Control, allow enterprise disable / allowlist / gateway escalation.

Why

The repo had no implementor-facing guidance on when/why to serve a card or how a client should discover and offer servers. This collects recommendations on top of the normative mechanics in the README, discovery.md, and the AI Catalog spec.

Scope notes

• This PR standardizes on the AI Catalog (/.well-known/ai-catalog.json) as the discovery document, per maintainer direction to focus on AI Catalog and not the MCP Catalog. discovery.md still documents the older MCP Catalog; reconciling it is intentionally out of scope (tracked separately by Remove the MCP Catalog #26). The intro is scoped so the two docs don't actively contradict.

Verification

• npm run check passes (schema.json in sync with schema.ts; tsc compiles) — green in CI
• npm run validate passes (examples validate against schema.json) — green in CI
• npm run format:check / prettier passes on the new and edited Markdown — green in CI
• All internal anchors resolve (discovery.md#relationship-to-ai-catalog, #consistency-with-runtime-behavior, README.md#relationship-to-the-mcp-registry, intra-file #keep-probing-cheap-and-let-enterprises-scope-it)
• All Goose specifics (egress proxy + blocked.txt, lifecycle hooks, extension deep-link format, permission modes) verified against live goose-docs.ai
• No MCP-Catalog / well-known/mcp references introduced (grep-clean)
• Fresh-eyes review performed; feedback addressed
• No changes outside docs/ and README.md