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>

README.md

@@ -62,12 +62,13 @@ the review can still discover knowledge by reading the folders.
 
 | I want to... | Start here |
 | --- | --- |
+| Choose direct reading, a supplied skill, or my own agent | [Ways to use BCQuality](docs/using-bcquality.md#choose-how-to-use-bcquality) |
 | Review a file, changes, a branch, or a particular concern | [Using BCQuality](docs/using-bcquality.md) |
 | Resolve setup problems, incomplete reviews, or incorrect findings | [Troubleshooting and support](docs/troubleshooting.md) |
 | Browse the available guidance | [Knowledge by domain](docs/using-bcquality.md#knowledge-by-domain) |
 | Configure the plugin or use my organization's rules | [Customizing BCQuality](docs/customizing-bcquality.md) |
-| Contribute knowledge or improve a rule | [Contributing](docs/contributing.md) |
-| Connect a host, agent, or CI integration | [How agents consume BCQuality](docs/agent-consumption.md) |
+| Contribute knowledge or improve a rule | [Your first contribution](docs/contributing.md#your-first-contribution) |
+| Connect a host, agent, or CI integration | [Minimal integration example](docs/agent-consumption.md#try-a-minimal-integration) |
 
 [All documentation and technical references](docs/README.md).
 

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
 

microsoft/knowledge/performance/use-setloadfields-for-partial-records.md

@@ -11,11 +11,13 @@ application-area: [all]
 
 ## Description
 
-`SetLoadFields(...)` declares the subset of normal fields the next read should materialize, "reducing data read and transfer thereby improving performance significantly." Per the upstream guidance, "the gains scale with the amount of rows read, so for loops that read many rows `SetLoadFields` is even more important." Primary-key fields, `SystemId`, and system audit fields are loaded automatically, "and fields that are filtered on are also automatically included" — those do not need to appear in the list. `SetLoadFields` only affects `FieldClass = Normal`; it does not narrow FlowFields or FlowFilters. Its position relative to `SetRange`/`SetFilter` does not change the projection: filtered fields are added to the load set at read time either way. Projection-changing operations are separate: `AddLoadFields(...)` expands the selection, a later `SetLoadFields(...)` or `SetBaseLoadFields()` overwrites it, and `Reset()` or a fieldless `SetLoadFields()` restores all readable normal fields.
+`SetLoadFields(...)` declares the subset of normal fields the next read should materialize. Microsoft's partial-record guidance explains how loading fewer fields reduces work, particularly for read loops and tables with extensions. Primary-key fields, `SystemId`, system audit fields, and fields being filtered on are loaded automatically; those do not need to appear in the selection. Only `FieldClass = Normal` fields can be selected, not FlowFields or FlowFilters.
+
+Its position relative to `SetRange`/`SetFilter` does not change the projection: filtered fields are included at read time either way. Projection-changing operations are separate: `AddLoadFields(...)` expands the selection, a later `SetLoadFields(...)` or `SetBaseLoadFields()` overwrites it, and `Reset()` or a fieldless `SetLoadFields()` restores all readable normal fields. The Microsoft Learn references below document the selection and reset behavior.
 
 ## Best Practice
 
-Before a `Get`, `FindSet`, or `FindFirst` that the procedure follows by reading only a handful of the table's fields, call `SetLoadFields` listing exactly those fields. The pattern `SetLoadFields(...); if Record.Get(...) then ...` is the upstream-endorsed shape. Place the call immediately before the read, after any `SetRange`/`SetFilter`, so a reader can see at a glance which read the selection governs and any projection-changing operation is easy to spot. Skip `SetLoadFields` when the table has few fields (under ten), when the code reads most of them (above 60 %), when the loop runs ten or fewer iterations, or when the table is exempt for other reasons (`singleton-setup-tables-need-no-access-optimization.md`, `temporary-tables-have-no-database-cost.md`). For report dataitems, use `AddLoadFields` in `OnPreDataItem` instead (see `addloadfields-in-report-onpredataitem.md`).
+Before a `Get`, `FindSet`, or `FindFirst` that the procedure follows by reading only a handful of the table's fields, call `SetLoadFields` listing exactly those fields. For example, `SetLoadFields(...); if Record.Get(...) then ...` selects fields before the read. Place the call immediately before the read, after any `SetRange`/`SetFilter`, so a reader can see at a glance which read the selection governs and any projection-changing operation is easy to spot. Skip `SetLoadFields` when the table has few fields (under ten), when the code reads most of them (above 60 %), when the loop runs ten or fewer iterations, or when the table is exempt for other reasons ([singleton setup tables](singleton-setup-tables-need-no-access-optimization.md), [temporary tables](temporary-tables-have-no-database-cost.md)). The numeric cutoffs are BCQuality review heuristics, not Microsoft platform thresholds. For report dataitems, use `AddLoadFields` in `OnPreDataItem` instead (see [report partial loads](addloadfields-in-report-onpredataitem.md)).
 
 See sample: [`use-setloadfields-for-partial-records.good.al`](use-setloadfields-for-partial-records.good.al).
 
@@ -26,3 +28,8 @@ Loading a wide table and reading one field per row in a loop. The bytes transfer
 Statement order is not part of this anti pattern. `SetLoadFields` placed ahead of `SetRange`/`SetFilter` materializes exactly the same columns as the reverse order, so a reviewer reports it as a readability observation at most — never as a performance defect.
 
 See sample: [`use-setloadfields-for-partial-records.bad.al`](use-setloadfields-for-partial-records.bad.al).
+
+## References
+
+- [Record.SetLoadFields remarks](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/methods-auto/record/record-setloadfields-method#remarks): automatically loaded fields, normal-field restrictions, and resetting the selection.
+- [Using partial records](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-partial-records): performance rationale, load-selection APIs, reset behavior, and report guidance.