READ

Read this contract before interpreting knowledge files. Task execution starts at Entry; READ is loaded on demand when a dispatched skill needs it. It defines knowledge fields, their meaning, and how to reconcile files.

This contract is stable. Changes require a PR approved by both maintainers.

What a knowledge file is

A knowledge file is a single markdown file that covers one concern in Business Central development. It has:

• A YAML frontmatter block with the fields below. All fields are required.
• A ## Description section. Required.
• Optional sections — typically ## Best Practice and ## Anti Pattern, but any ## section is permitted.
• No fenced code blocks. Sample code lives in sibling files next to the article (see Sample files below).

A file that violates any of these rules is invalid and MUST be skipped by consumers. Do not attempt to partially parse invalid files.

Frontmatter schema (v1)

---
bc-version: [all]                       # or [26, 27, 28], the range [26..28], or the open-ended range [26..]
domain: performance
keywords: [query, filtering, partial]
technologies: [al]
countries: [w1]
application-area: [all]
---

All six fields are required. Missing or empty fields invalidate the file.

Fields

bc-version — Array. The Business Central major versions this file applies to. Four forms are accepted:

• Universal sentinel: [all] means the guidance applies to every BC version and matches any target.
• Explicit list: [26, 27, 28].
• Closed range shorthand: [26..28] means every integer from 26 through 28 inclusive.
• Open-ended range shorthand: [26..] means version 26 and every later version, with no upper bound. Use it for guidance tied to a feature introduced in a specific version that is not expected to be removed.

[all] is mutually exclusive with explicit versions; do not combine. Consumers MUST expand closed ranges to the full set before comparison; an open-ended range [N..] is not enumerable and instead matches any target version greater than or equal to N.

domain — String. A single domain tag that places the file within a broader area of concern. Standard values include performance, security, ux, telemetry, testing, api, pipelines, finance, supply-chain, manufacturing, jobs. New domains may be introduced by contributors; no closed enumeration is enforced at the schema level. Consumers MUST treat unknown domains as valid.

keywords — Array of strings. Free-text tags used for retrieval. Between 3 and 10 tags is typical. Tags are lowercase, kebab-case, and describe the concern in the vocabulary an engineer or agent would search for.

technologies — Array of strings. The technologies the file applies to. Examples: al, javascript, powershell, kql, azure-devops, github-actions. A file that applies across technologies lists all of them explicitly. The sentinel all is not permitted for this field.

countries — Array of strings. ISO 3166-1 alpha-2 country codes (lowercase: us, de, dk) for localization-specific guidance. Use the sentinel [w1] for guidance that applies worldwide. [w1] is mutually exclusive with country codes; do not combine.

application-area — Array of strings. The BC application areas the file applies to. Examples: finance, manufacturing, jobs, warehousing, service. Use the sentinel [all] for guidance that applies regardless of application area. [all] is mutually exclusive with specific areas.

Sections

## Description is required. It states the concern: what the topic is and why it matters. It is the primary retrieval target when a consumer decides whether a file is relevant.

Two further sections are recognized as normative — consumers MAY rely on their content for conflict detection and guidance extraction:

• ## Best Practice — the recommended approach.
• ## Anti Pattern — what to avoid and the reasoning.

Any other ## section is permitted and is non-normative: consumers MUST NOT treat its contents as binding guidance. Non-normative sections (for example ## See also or ## Applies to) are for human context; they are ignored by conflict detection and by the filtering rules below. Consumers MUST NOT fail on unknown sections.

Layer precedence

A knowledge file lives in one of three layers, determined by its path:

• /microsoft/knowledge/** — platform-endorsed.
• /community/knowledge/** — community-curated.
• /custom/knowledge/** — partner or customer overrides (typically in a consumer repo, not in BCQuality).

The default consumption model is additive: an action skill sees files from every enabled layer and may surface findings from all of them. A consumer MAY be configured to disable a layer; in that case, files in the disabled layer are invisible to the consumer.

When two files give directly contradictory normative guidance, the conflict is resolved by layer precedence:

1. /custom/ wins over /community/ and /microsoft/.
2. /community/ wins over /microsoft/.

A conflict exists when both of the following are true:

• Applicability overlaps. The files' frontmatter filters (bc-version, technologies, countries, application-area) have a non-empty intersection under the matching rules below. domain is a retrieval aid; it is not part of the applicability test.
• Normative guidance contradicts. Content in the ## Best Practice or ## Anti Pattern sections is logically incompatible (one recommends what the other forbids, or vice versa). Non-normative sections are not considered.

Conflict detection is the consumer's responsibility; BCQuality does not enforce conflict-free content. When a consumer suppresses a losing file due to precedence or configuration, it MUST record the suppression in its output (see DO) so reviewers can see what was overridden.

Frontmatter matching semantics

When a consumer filters or matches files against a task context, these rules apply:

• bc-version — the file matches if its set is [all], or if the target BC version is an element of the file's expanded bc-version set. Closed range shorthand ([26..28]) MUST be expanded before comparison; an open-ended range ([26..]) matches when the target BC version is greater than or equal to its lower bound.
• technologies — non-empty intersection between the task's technologies and the file's technologies. There is no sentinel for this field.
• countries — the file matches if its set contains w1, or if there is a non-empty intersection with the task's countries.
• application-area — the file matches if its set contains all, or if there is a non-empty intersection with the task's application areas.

A file is applicable to a task when all four rules match. Applicability is also the basis for conflict detection above.

When the task context is partial

A task context may omit one or more dimensions (for example, a skill invoked against a raw file path with no known target BC version). For any omitted dimension:

• If the file's value for that dimension is a universal sentinel (all for bc-version, w1 for countries, all for application-area), the rule matches.
• Otherwise the rule is treated as unknown, not as a match and not as a failure.

A file with any unknown rule is conditionally applicable. A consumer MAY include conditionally applicable files in the worklist; if it does, every finding derived from such a file MUST have confidence no higher than medium and MUST record the unknown dimensions in the finding's message. A consumer MAY be configured to exclude conditionally applicable files entirely.

Consumers MUST NOT silently treat missing context as a match.

Citing a knowledge file

A consumer that produces output referencing a knowledge file MUST cite it by its repo-relative path (for example, microsoft/knowledge/performance/apply-filters-before-iterating.md). Line numbers are not stable references; use the file path only. If a commit SHA is available to the consumer, it SHOULD be included alongside the path.

Sample files

Knowledge files MUST NOT contain fenced code blocks. When an article needs to show code, it ships the code as one or more sibling files next to the article, using this naming convention:

<layer>/knowledge/<domain>/<slug>.md         # the article
<layer>/knowledge/<domain>/<slug>.good.al    # best-practice demonstration
<layer>/knowledge/<domain>/<slug>.bad.al     # anti-pattern demonstration

Rules:

• A sample file is identified by the article's slug followed by a .<kind>.<ext> suffix. The supported kinds are good and bad. Additional kinds MAY be introduced by a layer; consumers MUST ignore unknown kinds without failing.
• The extension matches the technology (al, ps1, js, kql, …). A single article MAY carry samples in multiple technologies if the article's frontmatter technologies lists them.
• Articles MAY have a good sample only, a bad sample only, both, or neither. The article text SHOULD reference each sample it ships with a relative Markdown link whose label retains the backticked filename, like [`<slug>.good.al`](<slug>.good.al).
• Samples are demonstration-only. They are not deployed, not compiled as part of a published app, and not derived from the Business Central base application source. Each sample is self-contained and exists purely to make the accompanying article concrete for humans and agents.
• Layer precedence applies to sample files the same way it applies to articles: a /custom/knowledge/<domain>/<slug>.good.al overrides a /microsoft/knowledge/<domain>/<slug>.good.al for the same article in the same layer hierarchy.

Consumers that surface sample code to an end user or agent SHOULD cite the sample file by its repo-relative path, in the same format as article citations.

Retrieval workflow

The standard workflow for finding applicable files:

1. Collect candidates from the knowledge index (knowledge-index.json). BCQuality maintains it: Entry's preparation step (see entry.md) regenerates it over the live, already-filtered clone, so it lists exactly the articles that survived the consumer's layer/allow-deny pruning, each with the frontmatter, keywords, title, and one-line description that steps 2-3 need — candidates are enumerated without opening each file. The index is discovery metadata only: it tells you which files to open, it does not substitute for them. A finding MUST cite only an article that was opened and read in full; an index row whose file is absent from the clone MUST be discarded before ranking or worklisting, and its metadata MUST NOT seed a finding. Absent an index, collect candidates by path (typically by domain subfolder, across enabled layers).
2. Filter by frontmatter using the matching rules above. Files that are not applicable are discarded.
3. Rank or narrow by keywords relevance to the task.
4. Resolve conflicts via layer precedence.

Steps 1–3 are deterministic; step 4 is applied only when conflicts are detected.

Bounded retrieval for review skills

Resolve $root to the BCQuality root, not the reviewed source. Entry prepares the index once before dispatch; that prepared index is the catalog snapshot and leaves use it read-only. Catalog retrieval validates the complete index metadata and returned paths without reopening or rehashing article bodies. Post-Entry body changes therefore take effect only after Entry rebuilds the index; exact body retrieval rejects a selected article whose content hash differs from its prepared row. In one PowerShell tool session, invoke the helpers with & so array arguments remain arrays:

& (Join-Path $root 'tools\Search-Knowledge.ps1') -Domain $domain -Technologies @('al')
& (Join-Path $root 'tools\Get-KnowledgeArticles.ps1') -Paths @($exactPath)

Pass enabled layers and only task dimensions that are actually known. Catalog retrieval returns every domain and READ-applicable row: it does not rank, sample, apply top-k, deduplicate by basename, or omit rows based on query text. Consume every page by passing continuation.offset as -Offset and continuation.snapshot as -Snapshot with the unchanged request until complete is true. Each page repeats request context, defaults, and totals. An omitted applicability field on a row inherits that page's defaults; it does not mean unknown task context. Preserve every row's exact path, layer, complete keywords, title, one-line description, non-default applicability fields, explicit applicability, and unknownDimensions.

Apply the leaf's existing Relevance and Worklist to the complete catalog union. Split the resulting exact paths into stable chunks of at most eight; never pass more paths than -MaxArticles (whose maximum is eight). Request article bodies only by one such chunk. Consume every returned body, then request remainingPaths with continuation.snapshot as -Snapshot until complete is true, preserving the other request settings. Continuation is confined to that chunk. Bodies are original strict UTF-8 text with source byte counts and SHA-256 content hashes; they are never summarized or truncated. Samples are not loaded unless requested explicitly with -Samples and exact sibling paths; their sibling article must match its prepared hash and contain the exact READ link.

The default serialized response limit is 16,000 bytes including its output newline. Never combine pages or bodies into an unbounded prompt. A malformed or internally inconsistent prepared index, changed continuation snapshot, selected article hash mismatch, invalid continuation, unsafe or missing path, invalid UTF-8, broken sample link, oversized path chunk, or row/envelope that cannot fit fails explicitly. Entry is the only index preparation point: a leaf does not rebuild. If PowerShell, a helper, or a valid prepared index is unavailable, discover exact paths across the enabled domain folders and use native bounded reads through EOF, validating frontmatter per READ and never treating retrieval failure as an empty result.

The helpers' sha256 and bytes fields describe the retrieved file content. They are not citation provenance. Optional findings references[].sha is the BCQuality commit SHA the skill reviewed; omit it when that provenance is not available or would misrepresent uncommitted content.