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/vendor/add.go

@@ -150,7 +150,9 @@ func discoveryFromTreeRoot(root string) lockfile.Discovery {
 func checkIncludeEntries(items []discovery.Item, include []string, name string) error {
 	available := map[string]bool{}
 	for _, it := range items {
-		available[it.UpstreamID] = true
+		if !it.Skipped {
+			available[it.UpstreamID] = true
+		}
 	}
 	for _, want := range include {
 		if !available[want] {
@@ -171,6 +173,9 @@ func applySelection(items []discovery.Item, sel lockfile.Selection) []discovery.
 	}
 	var out []discovery.Item
 	for _, it := range items {
+		if it.Skipped {
+			continue
+		}
 		switch sel.Mode {
 		case lockfile.ModeInclude:
 			if include[it.UpstreamID] {
@@ -216,10 +221,18 @@ func materialize(workDir, name string, tree discovery.Tree, selected []discovery
 }
 
 func reportAdd(w io.Writer, name string, src *lockfile.Source, discovered, selected []discovery.Item) {
+	real := 0
+	for _, it := range discovered {
+		if !it.Skipped {
+			real++
+		}
+	}
 	counts := func(items []discovery.Item) string {
 		per := map[string]int{}
 		for _, it := range items {
-			per[it.Type]++
+			if !it.Skipped {
+				per[it.Type]++
+			}
 		}
 		var parts []string
 		for _, t := range lockfile.Types {
@@ -236,7 +249,7 @@ func reportAdd(w io.Writer, name string, src *lockfile.Source, discovered, selec
 	fmt.Fprintf(w, "  url: %s\n", src.URL)
 	fmt.Fprintf(w, "  ref: %s\n", src.Ref)
 	fmt.Fprintf(w, "  rev: %s\n", src.Rev)
-	fmt.Fprintf(w, "discovered %d items (%s)\n", len(discovered), counts(discovered))
+	fmt.Fprintf(w, "discovered %d items (%s)\n", real, counts(discovered))
 	fmt.Fprintf(w, "selected   %d items (%s)\n", len(selected), counts(selected))
 	fmt.Fprintf(w, "materialized under %s/\n", filepath.Join(externalDir, name))
 	if len(src.Warnings) > 0 {