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

internal/discovery/discovery.go

@@ -36,6 +36,11 @@ type Item struct {
 	RelPath     string
 	Frontmatter *Frontmatter
 	Warnings    []string
+	// Skipped marks a file discovery recognized but deliberately excluded —
+	// e.g. a documentation .md under agents/ or commands/ without definition
+	// frontmatter. Skipped items carry warnings but must never enter a
+	// selection, inventory or availability listing.
+	Skipped bool
 }
 
 // Scan discovers items of all four content types under cfg. Discovery is a
@@ -156,6 +161,12 @@ func scanFlatFiles(tree Tree, fileEntries map[string]map[string]bool, root, typ
 			continue
 		}
 		it := Item{Type: typ, UpstreamID: id, RelPath: rel}
+		if !HasDefinitionFrontmatter(data) {
+			it.Skipped = true
+			it.Warnings = append(it.Warnings, fmt.Sprintf("%s: no %s frontmatter, skipped", rel, strings.TrimSuffix(typ, "s")))
+			items = append(items, it)
+			continue
+		}
 		fm, warnings := ParseFrontmatter(data)
 		it.Frontmatter = &fm
 		for _, w := range warnings {