feat(discovery): frontmatter guard for flat agents/commands docs

A flat .md under agents/ or commands/ whose frontmatter contains none of
the definition keys (name, description, mode, agent, model,
argument-hint, temperature, permission) is documentation, not an item:
discovery marks it Skipped with a recorded warning — it never enters a
selection, inventory, availability listing or collision index, but the
warning lands in the lockfile and add/update/select reports like other
discovery warnings. Skills keep their folder+SKILL.md marker, MCP keeps
the .yaml marker. README gains the canonical layout table and the
migration note for folder-style agent repos.

Closes beads: agent-lib-2n7

README.md

@@ -47,6 +47,22 @@ external/<source>/<type>/ vendored content, mirrors the same four types
 agent-lib.lock.json       lockfile v2 — pins every source
 ```
 
+This layout is **exactly** what OpenCode natively consumes — agent-lib is
+deliberately on the opencode standard, no conversion layer:
+
+| Type | Canonical form |
+|---|---|
+| skills | `<id>/SKILL.md` folder (any depth, category nesting ok) |
+| commands | flat `commands/<id>.md` |
+| agents | flat `agents/<id>.md` |
+| mcp | flat `mcp/<id>.yaml` (inventoried, never deployed) |
+
+**Migrating from folder-style agent repos** (e.g. `agents/<id>/AGENT.md`
+layouts): flatten `agents/<id>/AGENT.md` → `agents/<id>.md`, and move
+documentation and manifests (`SCHEMA.md`, `agents.json`, `README.md`) out of
+the typed directories. No folder support for agents/commands is planned —
+adapting the source repo to the standard beats shipping a renderer.
+
 ### Vendoring a source
 
 ```sh
@@ -61,8 +77,12 @@ standard directories (`skills/`, `commands/`, `agents/`, `mcp/`); skills are
 folders containing `SKILL.md` — found at **any depth**, so category-nested
 layouts (`skills/engineering/tdd/SKILL.md`) work too, with the folder's base
 name as the skill id — commands and agents are flat `.md` files, MCP
-fragments are `.yaml`. Everything is read-only scanned — upstream code is
-never executed.
+fragments are `.yaml`. A flat `.md` under `commands/` or `agents/` whose
+frontmatter contains none of the definition keys (`name`, `description`,
+`mode`, `agent`, `model`, `argument-hint`, `temperature`, `permission`) is
+treated as dropped documentation: skipped with a recorded warning, never an
+inventory entry. Everything is read-only scanned — upstream code is never
+executed.
 
 ### Selection rules