docs: convention for integration repository structure and naming

[Maya Wang (mayawang)]

Summary

Adds docs/integration-repos.md: where end-to-end integrations live, how their
repositories are named, and how the fixes they need flow back into core.

The convention in one line — trivial demos stay in the core repo, each
non-trivial integration gets one dedicated repo under the agent-substrate
org, and core gaps get closed by making core configurable with defaults
unchanged rather than by patching it downstream.

Why now

We are about to create the first real, end-to-end integrations rather than
counter-style demos: a code-execution sandbox, and an always-on agent. Both are
large enough to need their own images, dependencies, and release cadence.

Whichever repository gets created first will set the precedent for every one
after it. This writes the convention down so that precedent is chosen
deliberately instead of inherited by accident.

What it covers

• Where code lives — the core-repo/dedicated-repo split, the rough test for
  which side something falls on (API keys, external services, third-party
  accounts), and why this is a set of peer repos rather than a second org.
• Naming — capability-named for general capabilities
  (code-execution-sandbox), integration-named for specific third-party
  products, named for the product rather than the vendor behind it. Plus what to
  avoid: over-broad names, names that clone a vendor's API or brand, and the
  redundant -integration suffix.
• Third-party names — allowed descriptively, with a non-affiliation note in
  the repo README, and brand/policy edge cases cleared before the repo exists.
• Upstreaming — the part with teeth for this repo. Integration repos that
  accumulate local patches against core bitrot, and the gap they work around
  stays invisible to everyone else. So: prefer making core behavior configurable
  with defaults unchanged. feat: readyz: make the overall wait timeout configurable per template #487 and Suspend-safe actor networking via injected in-sandbox ingress/egress proxies #465 are linked as illustrations of that
  pattern — this PR does not depend on either, and branches from main.
• Two worked examples that validate the convention rather than just
  following it, including the third-party-name edge case.

Review

This was announced at the community meeting and circulated as a shared design
doc with a 7-day review window, which has now closed. It synthesizes the
#integrations thread discussion. Comment history:

https://docs.google.com/document/d/1Tb6u0b1XSvWrNpoyD4jdsQaJ58aAgDtQOM18uxujs-8/edit

This PR is the trimmed version: doc-review scaffolding — status block, reviewer
list, self-link — is dropped, and only the durable convention is carried over.

Left open

Two questions are deliberately out of scope, called out in the doc rather than
answered. Both are maintainer calls and neither blocks the first repositories:

• Governance tiers — whether to distinguish "official" from "community"
  integrations with different review bars, as Home Assistant and Obsidian do.
• Who creates integration repositories and grants per-integration maintainer
  access.

Also in this PR

• README gets an entry in the docs list, matching every other file in docs/.
• CONTRIBUTING.md gets one sentence pointing there, since "where does my
  integration go?" is a question a contributor asks before opening a PR.

Fixes #<issue_number_goes_here>

It's a good idea to open an issue first for discussion.

• Tests pass
• Appropriate changes to documentation are included in the PR