internal/topdata/top_package.go

@@ -214,6 +214,9 @@ func collectTopPackageResources(p *project.Project, compiled2DADir string) ([]er
 			if strings.HasPrefix(filepath.Base(path), ".") {
 				return nil
 			}
+			if strings.EqualFold(filepath.Ext(path), ".md") {
+				return nil // docs (AGENTS.md, README.md, ...) are never HAK resources
+			}
 			resource, err := topPackageResourceFromPath(path)
 			if err != nil {
 				return err

internal/topdata/topdata.go

@@ -2233,6 +2233,9 @@ func validateTopPackageAssets(sourceDir, dataDir string, report *ValidationRepor
 		if strings.HasPrefix(filepath.Base(path), ".") {
 			return nil
 		}
+		if strings.EqualFold(filepath.Ext(path), ".md") {
+			return nil // docs (AGENTS.md, README.md, ...) are never HAK resources
+		}
 		base := strings.ToLower(strings.TrimSuffix(filepath.Base(path), filepath.Ext(path)))
 		ext := strings.TrimPrefix(strings.ToLower(filepath.Ext(path)), ".")
 		if _, ok := erf.HAKResourceTypeForExtension(ext); !ok {

internal/topdata/topdata_test.go

@@ -15115,3 +15115,23 @@ func writeBytes(t *testing.T, path string, content []byte) {
 		t.Fatalf("write %s: %v", path, err)
 	}
 }
+
+func TestValidateTopPackageAssetsSkipsMarkdown(t *testing.T) {
+	dir := t.TempDir()
+	assets := filepath.Join(dir, "assets", "gui")
+	if err := os.MkdirAll(assets, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(assets, "AGENTS.md"), []byte("docs"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	dataDir := filepath.Join(dir, "data")
+	if err := os.MkdirAll(dataDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	var report ValidationReport
+	validateTopPackageAssets(dir, dataDir, &report)
+	for _, d := range report.Diagnostics {
+		t.Errorf("unexpected diagnostic: %s: %s", d.Path, d.Message)
+	}
+}