Complete partner contribution and knowledge consumption guides

Explain direct reading, supplied skills, and custom-agent consumption. Add a first-contribution walkthrough and concrete integration bootstrap, and clarify SetLoadFields guidance with authoritative sources and explicit review heuristics.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

docs/README.md

@@ -8,12 +8,13 @@ of BCQuality's internal protocol is needed.
 
 | Goal | Guide |
 | --- | --- |
+| Choose direct reading, a supplied skill, or my own agent | [Ways to use BCQuality](using-bcquality.md#choose-how-to-use-bcquality) |
 | Review an app, file, changes, or branch | [Using BCQuality](using-bcquality.md) |
 | Understand a report and its limitations | [Reading your results](using-bcquality.md#reading-your-results) |
 | Find a particular rule or example | [Knowledge by domain](using-bcquality.md#knowledge-by-domain) |
 | Fix setup problems or report an incorrect finding | [Troubleshooting and support](troubleshooting.md) |
 | Select layers, add company rules, or maintain a fork | [Customizing BCQuality](customizing-bcquality.md) |
-| Add or improve shared knowledge | [Contributing](contributing.md) |
+| Add or improve shared knowledge | [Your first contribution](contributing.md#your-first-contribution) |
 
 ## Integration and technical reference
 
@@ -22,6 +23,7 @@ prerequisites for using the plugin.
 
 | Reference | Purpose |
 | --- | --- |
+| [Minimal integration example](agent-consumption.md#try-a-minimal-integration) | A bootstrap prompt connecting your agent to a BCQuality checkout and an app folder. |
 | [How agents consume BCQuality](agent-consumption.md) | Architecture, repository structure, routing, and delivery of findings. |
 | [Standalone runner](standalone-runner.md) | Optional model selection, scheduling, retries, and telemetry. |
 | [Global skills](../skills/README.md) | Host adapters versus internal protocol files. |

docs/agent-consumption.md

@@ -10,6 +10,65 @@ mental model.
 This is the operational reference for integration authors. Partners using
 the installed plugin do not need to implement this flow themselves.
 
+## Try a minimal integration
+
+**"Invoke `skills/entry.md`" means ask your agent to read and follow that
+instruction document.** It is not a shell command, HTTP endpoint, or executable
+library. Your host must be able to read files, enumerate directories, and
+execute the selected skills as instructed. Merely mentioning BCQuality does
+not make its content available to the model.
+
+For a first integration, create or reuse a dedicated BCQuality checkout.
+For example, in PowerShell:
+
+```powershell
+git clone https://github.com/microsoft/BCQuality.git "C:\Knowledge\BCQuality"
+```
+
+Give the host access to **both** that content directory and your own app
+directory. The plugin is not required for this route. Replace the paths and
+BC version below with your actual values, then send this prompt to the agent:
+
+```text
+BCQuality root: C:\Knowledge\BCQuality
+Review input: folder-path = C:\Repos\MyBusinessCentralApp
+
+Read BCQuality's skills\entry.md and follow it with this task context:
+task-context:
+  goal: Review the complete AL app without changing its source files.
+  inputs-available: [folder-path]
+  technologies: [al]
+  bc-version: 28
+  enabled-layers: [microsoft, community, custom]
+  disabled-skills: []
+
+Resolve BCQuality instructions, knowledge, and index preparation against the
+BCQuality root, not the app directory. Pass the actual review-input path above
+when a dispatched skill accepts folder-path.
+Follow Entry's preparation and dispatch instructions. Execute every dispatched
+action skill with its exact input subset, reading READ and DO on demand.
+Return each complete findings report unchanged. If Entry returns no-match or
+failed, return that dispatch record unchanged instead of inventing a review.
+```
+
+`inputs-available` lists input **types**; the `Review input` line binds the type
+to the actual app directory. It is not an extra Entry schema field. Omit
+`bc-version` when unknown rather than guessing it; add localization or
+application-area context only when known. Keep the two roots distinct so index
+preparation operates on BCQuality, not your app.
+
+Expect Entry to select the action skills and the agent to execute them.
+A broad review normally returns the Microsoft coordinator's report with
+domain `sub-results`, plus any separately dispatched reports. Each report
+must retain its outcome, including incomplete or failed work; see
+[reading results](using-bcquality.md#reading-your-results). A dispatch record
+alone is not a completed review.
+
+This prompt delegates the existing protocol rather than implementing new
+routing logic. For repeatable runs, [pin the checkout](customizing-bcquality.md#updates-and-versions).
+Add scheduling, retries, and rendering only when needed, using the
+[runner contract](standalone-runner.md).
+
 ## The actors
 
 - **Orchestrator** — the tool that triggers work. Lives *outside* BCQuality. Knows *when* to run something, not *what* to run.

docs/contributing.md

@@ -6,6 +6,34 @@ Partners are welcome to contribute shared knowledge, examples, skills, and
 documentation. To report an incorrect finding without preparing a change,
 use the [support guide](troubleshooting.md#reporting-a-problem).
 
+## Your first contribution
+
+You can propose shared guidance without write access to the upstream
+repository. Use this path for a correction or a new article:
+
+1. Search the [existing knowledge](using-bcquality.md#knowledge-by-domain) and
+   [open issues](https://github.com/microsoft/BCQuality/issues). Correct or
+   extend an existing article when it already owns the concern; add a new
+   article only for a distinct concern that meets the admission test below.
+2. [Fork BCQuality](https://github.com/microsoft/BCQuality/fork) into your GitHub
+   account or organization, clone your fork, and create a working branch from
+   the current upstream `main`. Make edits in that branch, not the plugin cache.
+3. Choose the [owning layer and domain](#choose-the-right-destination), then
+   edit the article or use the [shared-article starter](#shared-article-starter).
+   A contribution intended for everyone does not belong in `custom/`.
+4. Add supporting sources and relevant good/bad samples. For a false positive,
+   explain the valid pattern and the mistaken finding the rule should prevent.
+5. Run the [documented checks](#before-opening-a-pr), then commit and push
+   your branch to your fork.
+6. On GitHub, open a pull request with **base repository
+   `microsoft/BCQuality`, base branch `main`**, and your fork's working branch
+   as the head. Explain why the change is needed and respond to review by
+   pushing further commits to the same branch.
+
+Merged content is not automatically loaded into an existing agent session.
+Consumers must pick up the updated content through their installation or
+checkout; see [updates and versions](customizing-bcquality.md#updates-and-versions).
+
 ## What belongs here
 
 BCQuality is a remedial knowledge base. A knowledge file exists because a
@@ -69,6 +97,20 @@ to catch in `Anti Pattern`; those are the normative sections. Explain
 legitimate exceptions so a reviewer does not turn a useful rule into a false
 positive. Code fences are not allowed in knowledge articles.
 
+### Shared-article starter
+
+Use [caption-required-on-page-fields.md](../microsoft/knowledge/style/caption-required-on-page-fields.md)
+as a complete shared-knowledge example. It demonstrates all six metadata
+fields, a clear concern, normative guidance and exceptions, linked good/bad
+samples, and authoritative sources.
+
+For a new concern, follow that structure but choose your own descriptive
+filename, domain, applicability, keywords, and guidance. Replace its sources
+and sample links with ones supporting your concern; do not duplicate the
+caption rule. If you are correcting caption guidance itself, edit the
+existing article instead. Use a company-only rule only in your fork's Custom
+layer, following the separate [customization example](customizing-bcquality.md#add-an-organization-specific-rule).
+
 ### Sources and examples
 
 When adding or changing a platform claim, link the authoritative source that

docs/standalone-runner.md

@@ -12,6 +12,9 @@ Use the built-in standalone plugin when the host's default execution is
 sufficient. Build a runner when you need explicit control over cost, latency,
 concurrency, or integration with another review surface.
 
+Start with the [minimal integration example](agent-consumption.md#try-a-minimal-integration)
+to connect your agent to the content before adding runner-specific behavior.
+
 ## Keep BCQuality current
 
 For plugin installation, use the [quick start](../README.md#quick-start).

docs/using-bcquality.md

@@ -2,10 +2,55 @@
 
 [Documentation](README.md) | [Quick start](../README.md#quick-start) | [Troubleshooting](troubleshooting.md)
 
-BCQuality supplies knowledge and reusable skills to your AI host. The plugin
-currently exposes `al-code-review`; the examples below use that skill. The
-host supplies authentication, model access, tools, permissions, and rendering.
-Installing BCQuality does not install a Business Central extension or an agent.
+BCQuality is knowledge you can read and reuse, plus skills that tell an agent
+how to apply it. You do not need an AI tool to read the articles. When using
+an agent, your host supplies authentication, model access, tools, permissions,
+and rendering; BCQuality does not install a BC extension or an agent.
+
+## Choose how to use BCQuality
+
+| Path | What to do |
+| --- | --- |
+| Read the knowledge yourself | Browse [knowledge by domain](#knowledge-by-domain), or search the repository for an AL concept. Read the article and its samples. No installation required. |
+| Use a supplied skill | Follow the [plugin quick start](../README.md#quick-start). The currently exposed skill, `al-code-review`, performs reviews and returns findings. |
+| Use your own agent or workflow | Supply selected articles as context, as described below, or use the [integration bootstrap](agent-consumption.md#try-a-minimal-integration) to execute BCQuality action skills without the plugin. |
+
+### Read and reuse an article
+
+Start with a concern, such as `SetLoadFields`, and search within
+`microsoft/BCQuality` on GitHub or open its domain folder. For example,
+[partial-record guidance](../microsoft/knowledge/performance/use-setloadfields-for-partial-records.md)
+explains the concern and links good/bad samples.
+
+Before applying an article, read its frontmatter, the small metadata block at
+the top:
+
+| Field | How to read it |
+| --- | --- |
+| `bc-version` | `[24..]` means BC 24 and later; `[26..28]` means BC 26 through 28; `[all]` means every version. Use your target BC major version, not your extension's version. |
+| `technologies` | `[al]` means the guidance applies to AL; multiple values identify the technologies the article covers. |
+| `countries` | `[w1]` means worldwide; a code such as `[dk]` limits the guidance to that localization. |
+| `application-area` | `[all]` means any application area; a named area narrows applicability. |
+| `domain` and `keywords` | Help you find the topic; they are not instructions or additional requirements. |
+
+Read `Description` for context, then `Best Practice` and `Anti Pattern` for the
+rule and its exceptions. Follow any sample and source links. Do not turn a
+sample into a production implementation without considering your own context.
+The [READ reference](../skills/read.md) defines the precise matching rules.
+
+To use an article with your own agent, give it access to the full article and
+relevant samples, not just a title or index row. For example, replace the
+bracketed values in this prompt:
+
+> Read [article URL or local path] and its linked samples. Apply the relevant
+> guidance while implementing [task] for BC [major version]. Explain which
+> guidance you used, cite the article, and identify any missing context.
+
+A URL only works if the host can retrieve it; otherwise provide the files
+directly. This is ordinary reuse of knowledge for explanation or code writing,
+**not a packaged code-generation skill or a complete BCQuality review**.
+For the structured review process, invoke a supplied skill or follow the
+integration protocol. The remaining sections describe the review workflow.
 
 ## Hosts and prerequisites