Improve partner onboarding and documentation navigation (#174)

Lead with a complete plugin quick start and add task-oriented usage, troubleshooting, customization, and contribution guides. Preserve the broader plugin framing, correct conflicting contract guidance, support Agents folder reviews, and align repository validation. Convert existing sample references to clickable links without changing knowledge rules.

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

.github/custom-layer-autoclose.md

@@ -1,23 +1,19 @@
-Hey @{{AUTHOR}} 👋
+Thank you for contributing, @{{AUTHOR}}.
 
-First off — thank you for jumping in and experimenting! It's awesome to see people pushing on the framework. 🎉
+This PR was closed automatically because it changes custom-layer content.
+`custom/` is reserved for organization-specific knowledge and skills in
+**your own fork**, not the shared upstream repository.
 
-That said, let me gently redirect you, because I think there's a small but important misunderstanding about how the `custom` layer is meant to work:
+Keep company-only rules in your fork and point your host at that copy. The
+[customization guide](https://github.com/microsoft/BCQuality/blob/main/docs/customizing-bcquality.md)
+shows the complete flow.
 
-The `custom` layer in *this* repo isn't a destination for PRs — it's the designated sandbox inside **your own fork**. Think of it as the "your timeline" branch of the multiverse 🌌: this repo is canon, your fork is where you get to remix the lore without needing anyone's approval. That's the whole point of the layer existing — so you *don't* have to upstream your team-specific or experimental work.
-
-The intended workflow is:
-
-1. 🍴 **Fork** BCQuality to your own GitHub account
-2. Clone *your fork* locally
-3. Drop your custom agents and knowledge into the `custom` layer **there**
-4. Commit and push to your fork — no PR back to upstream needed for custom stuff
-
-That way you get full control, your changes survive upstream updates cleanly, and you can pull in new core releases from this repo whenever you want. ✨
-
-**Now — here's the fun part:** if while building out your fork you discover knowledge, patterns, or agents that you think would genuinely benefit *everyone* using BCQuality (not just your team), that's exactly what the `/community` layer is for! 🌟 PRs to `/community` here in the upstream repo are absolutely welcome and encouraged — it's how the collective hive mind 🧠 levels up. So please: tinker in your fork, and when you strike gold that's worth sharing, send it our way via `/community`.
-
-Going to close this PR for now (since it's targeting `custom` rather than `/community`), but please don't read it as a "no" — it's a "yes, but let's route it correctly." 🙏 Happy to help if you hit any snags spinning up your fork, and genuinely looking forward to seeing what you contribute to `/community` down the line.
+If the guidance is useful to everyone, submit it to the layer that owns the
+domain: Microsoft-owned domains belong under `microsoft/knowledge/`, even
+when contributed by a partner; Community-owned domains belong under
+`community/knowledge/`. See
+[Contributing](https://github.com/microsoft/BCQuality/blob/main/docs/contributing.md).
+BCQuality contains knowledge and skills, not agents.
 
 <details>
 <summary>Files in this PR that triggered the auto-close</summary>
@@ -25,7 +21,5 @@ Going to close this PR for now (since it's targeting `custom` rather than `/comm
 {{FILES}}
 </details>
 
-May your merges be conflict-free. 🚀
-
----
-<sub>🤖 This PR was closed automatically by the `Guard custom layer` workflow because it adds or changes content under `/custom/`. If you were only updating the template (`custom/README.md` or a `.gitkeep`), a maintainer can re-open it. If you think this was closed in error, just comment here.</sub>
+Template changes to `custom/README.md` and `.gitkeep` files are allowed. If
+you believe this closure was a mistake, comment here for maintainer review.

.github/new-top-level-flag.md

@@ -3,7 +3,7 @@
 
 {{ENTRIES}}
 
-This isn't a block — just a flag. 🚩 New top-level folders and files are *usually* unintended (a stray export, a tool's scratch dir, or content that meant to land inside an existing layer like `/community/knowledge/`). BCQuality keeps a deliberately small root: `.github/`, `community/`, `custom/`, `microsoft/`, `skills/`, and `tools/`, plus a handful of root docs.
+This isn't a block — just a flag. 🚩 New top-level folders and files are *usually* unintended (a stray export, a tool's scratch dir, or content that meant to land inside an existing layer). BCQuality keeps a deliberately small root: plugin metadata, `community/`, `custom/`, `microsoft/`, `skills/`, `tools/`, `docs/`, `evaluation/`, `.github/`, and a handful of root docs. Partner guides belong under `docs/`; shared knowledge belongs beside the skill that owns its domain.
 
 **If this was intentional** and the new entry genuinely belongs at the repo root, a maintainer can review and merge as normal — no action needed beyond a quick sanity check. **If it wasn't**, please move the content into the right existing layer (or drop it) and push an update. 🙏
 

.github/scripts/validate_frontmatter.py

@@ -45,7 +45,7 @@ ENTRY_SKILL_REQUIRED_KEYS = {"kind", "id", "version", "title"}
 HOST_SKILL_REQUIRED_KEYS = {"name", "description"}
 
 STANDARD_INPUTS = {
-    "pr-diff", "object-list", "file-path", "repository", "telemetry-query",
+    "pr-diff", "object-list", "file-path", "folder-path", "repository", "telemetry-query",
 }
 ALLOWED_OUTPUTS = {"findings-report"}
 VALID_SAMPLE_KINDS = {"good", "bad"}

.github/workflows/flag-new-top-level.yml

@@ -40,11 +40,12 @@ jobs:
             // Known, intended repository root. Anything else added at the root
             // is flagged for a human to eyeball.
             const ALLOWED_DIRS = new Set([
-              '.claude-plugin', '.github', 'community', 'custom', 'microsoft', 'skills', 'tools',
+              '.claude-plugin', '.github', 'community', 'custom', 'docs', 'evaluation',
+              'microsoft', 'skills', 'tools',
             ]);
             const ALLOWED_FILES = new Set([
               '.gitignore', 'CODEOWNERS', 'LICENSE', 'README.md',
-              'SECURITY.md', 'agent-consumption.md',
+              'SECURITY.md', 'plugin.json',
             ]);
 
             const MARKER = '<!-- guard:new-top-level -->';