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>

microsoft/knowledge/data-modeling/check-blocked-in-referencing-code-not-in-master.md

@@ -19,10 +19,10 @@ Putting the block check inside the master's own `OnInsert`/`OnModify` does nothi
 
 The referencing line validates `Master.TestField(Blocked, false)` in `OnValidate` of the reference field and re-checks before posting. The master table stays logic-free on `Blocked`.
 
-See sample: `check-blocked-in-referencing-code-not-in-master.good.al`.
+See sample: [`check-blocked-in-referencing-code-not-in-master.good.al`](check-blocked-in-referencing-code-not-in-master.good.al).
 
 ## Anti Pattern
 
 The block check sits in the master's own `OnModify`/`OnInsert` (so referencing and posting proceed unchecked), or there is no check at all on the referencing side.
 
-See sample: `check-blocked-in-referencing-code-not-in-master.bad.al`.
+See sample: [`check-blocked-in-referencing-code-not-in-master.bad.al`](check-blocked-in-referencing-code-not-in-master.bad.al).

microsoft/knowledge/data-modeling/master-table-no-from-number-series-in-oninsert.md

@@ -19,10 +19,10 @@ This is not an `Integer` `AutoIncrement` key, a GUID, or the `SystemId`. Those a
 
 `No.` `Code[20]` is the sole primary key; a non-editable `No. Series` `Code[20]` field records the source series. `OnInsert` checks `if "No." = ''`, reads the setup table, `TestField`s the configured series, stores it in `No. Series`, and assigns `No.` from the series.
 
-See sample: `master-table-no-from-number-series-in-oninsert.good.al`.
+See sample: [`master-table-no-from-number-series-in-oninsert.good.al`](master-table-no-from-number-series-in-oninsert.good.al).
 
 ## Anti Pattern
 
 An `Integer` `AutoIncrement` (or GUID / `SystemId`) primary key used as the business key, with no `OnInsert` number assignment. Records get an opaque identifier no user can reference, and the master no longer participates in the standard numbering and manual-entry behavior every other BC master follows.
 
-See sample: `master-table-no-from-number-series-in-oninsert.bad.al`.
+See sample: [`master-table-no-from-number-series-in-oninsert.bad.al`](master-table-no-from-number-series-in-oninsert.bad.al).

microsoft/knowledge/data-modeling/owning-table-must-delete-dependents-in-ondelete.md

@@ -25,7 +25,7 @@ See also `validate-table-relation-false-suppresses-rename-propagation.md` for th
 
 The owning table implements `OnDelete` and deletes its dependents there, filtered on the foreign key. Declare `Permissions = tabledata <dependent> = rd` on the owning table — granting delete rights only on the parent is a common miss that makes the trigger fail for a non-`SUPER` user. This mirrors the base application, where every header table deletes its own lines.
 
-See sample: `owning-table-must-delete-dependents-in-ondelete.good.al`.
+See sample: [`owning-table-must-delete-dependents-in-ondelete.good.al`](owning-table-must-delete-dependents-in-ondelete.good.al).
 
 ## Anti Pattern
 
@@ -33,4 +33,4 @@ A parent table with dependent rows and no `OnDelete` trigger, where the dependen
 
 Detection signal: a table declares `TableRelation` to table X, and table X has no `OnDelete` trigger. Whether a delete path currently exists in the UI is irrelevant to the finding.
 
-See sample: `owning-table-must-delete-dependents-in-ondelete.bad.al`.
+See sample: [`owning-table-must-delete-dependents-in-ondelete.bad.al`](owning-table-must-delete-dependents-in-ondelete.bad.al).

microsoft/knowledge/data-modeling/set-last-date-modified-in-onmodify-and-onrename.md

@@ -19,10 +19,10 @@ The reason is a BC-specific trap: renaming a record changes its primary key and
 
 Both `OnModify` and `OnRename` set `"Last Date Modified" := Today();`, and the field is declared `Editable = false` so only the triggers maintain it.
 
-See sample: `set-last-date-modified-in-onmodify-and-onrename.good.al`.
+See sample: [`set-last-date-modified-in-onmodify-and-onrename.good.al`](set-last-date-modified-in-onmodify-and-onrename.good.al).
 
 ## Anti Pattern
 
 Only `OnModify` assigns `Last Date Modified`. After a rename the value is stale, and any process that trusts it to detect changes misses the record.
 
-See sample: `set-last-date-modified-in-onmodify-and-onrename.bad.al`.
+See sample: [`set-last-date-modified-in-onmodify-and-onrename.bad.al`](set-last-date-modified-in-onmodify-and-onrename.bad.al).

microsoft/knowledge/data-modeling/setup-table-is-a-singleton.md

@@ -19,10 +19,10 @@ The setup **card** page enforces the singleton: `InsertAllowed = false` and `Del
 
 `Primary Key` `Code[10]` is the sole key; the setup is surfaced through a Card page with `InsertAllowed = false`, `DeleteAllowed = false`, and an open-time guard that inserts the blank row if it is missing.
 
-See sample: `setup-table-is-a-singleton.good.al`.
+See sample: [`setup-table-is-a-singleton.good.al`](setup-table-is-a-singleton.good.al).
 
 ## Anti Pattern
 
 An `Integer` / `AutoIncrement` key, a page that allows insert or delete, or a List page over the setup table. Any of these lets the table hold zero or many rows, so "the setup" becomes ambiguous and `Get()` may fail or read the wrong record.
 
-See sample: `setup-table-is-a-singleton.bad.al`.
+See sample: [`setup-table-is-a-singleton.bad.al`](setup-table-is-a-singleton.bad.al).

microsoft/knowledge/data-modeling/share-mediaset-items-with-insert-not-field-assignment.md

@@ -17,10 +17,10 @@ application-area: [all]
 
 When sharing media between different tables, iterate the source `MediaSet` and call `Target.MediaSetField.Insert(Source.MediaSetField.Item(Index))`, then modify the target record. Direct field assignment is safe only when source and target are the same record subtype and use the same field ID. This concern is about reference/delete integrity, not the separate performance cost of `ModifyAll` on tables with media fields.
 
-See sample: `share-mediaset-items-with-insert-not-field-assignment.good.al`.
+See sample: [`share-mediaset-items-with-insert-not-field-assignment.good.al`](share-mediaset-items-with-insert-not-field-assignment.good.al).
 
 ## Anti Pattern
 
 `Target.Picture := Source.Picture;` where the two variables refer to different table types or different media-field IDs. The code copies an opaque ID, but the platform does not know that two independent fields now share the media object.
 
-See sample: `share-mediaset-items-with-insert-not-field-assignment.bad.al`.
+See sample: [`share-mediaset-items-with-insert-not-field-assignment.bad.al`](share-mediaset-items-with-insert-not-field-assignment.bad.al).

microsoft/knowledge/data-modeling/table-relation-extensions-are-additive-and-top-down.md

@@ -17,10 +17,10 @@ A `tableextension` can add to an existing `TableRelation`, but the combined rela
 
 When a relation is designed to follow an extensible enum, express the base cases as conditional branches and leave no unconditional catch-all ahead of future extension branches. An enum extension can then append a condition for its new value. When extending a field you do not own, inspect the original `TableRelation`; do not claim that an appended condition overrides an unconditional relation.
 
-See sample: `table-relation-extensions-are-additive-and-top-down.good.al`.
+See sample: [`table-relation-extensions-are-additive-and-top-down.good.al`](table-relation-extensions-are-additive-and-top-down.good.al).
 
 ## Anti Pattern
 
 A base field has an unconditional `TableRelation = Customer;` and a `tableextension` adds `if (Type = const(Resource)) Resource`. The original unconditional branch always wins, so the new enum value still validates and looks up against Customer. The concern is evaluation order, not `ValidateTableRelation`; free-form input is covered separately by security guidance.
 
-See sample: `table-relation-extensions-are-additive-and-top-down.bad.al`.
+See sample: [`table-relation-extensions-are-additive-and-top-down.bad.al`](table-relation-extensions-are-additive-and-top-down.bad.al).

microsoft/knowledge/data-modeling/transferfields-skip-type-mismatch-can-drop-data.md

@@ -17,10 +17,10 @@ application-area: [all]
 
 Use `TransferFields(Source)` only when every field the destination requires, including primary key fields, is guaranteed to share a matching field number and type with the source; this form defaults `InitPrimaryKeyFields` to `true`. Fields with no matching field number, and fields whose types differ across extensions, are skipped regardless of `SkipFieldsNotMatchingType` — that parameter only governs same-extension type mismatches. If the destination depends on a field that falls into either case, map and validate it explicitly in code rather than relying on `TransferFields` to catch the gap. Use `SkipFieldsNotMatchingType = true` only when skipping same-extension type mismatches is an intentional, documented part of the transfer contract.
 
-See sample: `transferfields-skip-type-mismatch-can-drop-data.good.al`.
+See sample: [`transferfields-skip-type-mismatch-can-drop-data.good.al`](transferfields-skip-type-mismatch-can-drop-data.good.al).
 
 ## Anti Pattern
 
 Using `TransferFields(Source, InitPrimaryKeyFields, true)` as a generic way to make two evolving table schemas transfer without errors, when the destination depends on every required source field being copied. A type change on either table can turn a previously transferred field into a silently skipped one without making the transfer itself fail.
 
-See sample: `transferfields-skip-type-mismatch-can-drop-data.bad.al`.
+See sample: [`transferfields-skip-type-mismatch-can-drop-data.bad.al`](transferfields-skip-type-mismatch-can-drop-data.bad.al).

microsoft/knowledge/data-modeling/use-no-series-codeunit-not-noseriesmanagement.md

@@ -19,10 +19,10 @@ LLMs reproduce the legacy `NoSeriesManagement` pattern because it dominates pre-
 
 `OnInsert` assigns the number with `NoSeries.GetNextNo("No. Series")` where `NoSeries` is `Codeunit "No. Series"`. The `No.` field's `OnValidate` guards manual entry by calling `NoSeries.IsManual(...)` (or `TestManual`) before clearing `No. Series`.
 
-See sample: `use-no-series-codeunit-not-noseriesmanagement.good.al`.
+See sample: [`use-no-series-codeunit-not-noseriesmanagement.good.al`](use-no-series-codeunit-not-noseriesmanagement.good.al).
 
 ## Anti Pattern
 
 `NoSeriesMgt.InitSeries(...)` for assignment and `NoSeriesMgt.TestManual(...)` for the manual check, where `NoSeriesMgt` is `Codeunit NoSeriesManagement`. Both are obsolete-pending and emit compiler warnings.
 
-See sample: `use-no-series-codeunit-not-noseriesmanagement.bad.al`.
+See sample: [`use-no-series-codeunit-not-noseriesmanagement.bad.al`](use-no-series-codeunit-not-noseriesmanagement.bad.al).

microsoft/knowledge/data-modeling/validate-table-relation-false-suppresses-rename-propagation.md

@@ -27,7 +27,7 @@ See also `owning-table-must-delete-dependents-in-ondelete.md` for the delete hal
 
 Leave `ValidateTableRelation` at its default wherever the stored value must stay correct across a rename. When it must be disabled, or when the relationship cannot be expressed as a `TableRelation` at all, the table owning the referenced key carries an explicit `OnRename` that repoints the dependents itself.
 
-See sample: `validate-table-relation-false-suppresses-rename-propagation.good.al`.
+See sample: [`validate-table-relation-false-suppresses-rename-propagation.good.al`](validate-table-relation-false-suppresses-rename-propagation.good.al).
 
 ## Anti Pattern
 
@@ -35,4 +35,4 @@ See sample: `validate-table-relation-false-suppresses-rename-propagation.good.al
 
 Detection signal: any `ValidateTableRelation = false` on a field that also declares a `TableRelation`. Ask what repoints the value when the target is renamed; if the answer is "the platform", the finding stands.
 
-See sample: `validate-table-relation-false-suppresses-rename-propagation.bad.al`.
+See sample: [`validate-table-relation-false-suppresses-rename-propagation.bad.al`](validate-table-relation-false-suppresses-rename-propagation.bad.al).

microsoft/knowledge/data-modeling/xrec-is-a-before-image-only-in-some-triggers.md

@@ -25,7 +25,7 @@ See also `validate-table-relation-false-suppresses-rename-propagation.md`, which
 
 Use `xRec` for the previous key in `OnRename`, and for the record being removed in `OnDelete`. In `OnModify`, obtain the before-image by re-reading the stored row rather than trusting `xRec`, so the logic behaves identically whether a page, a job queue or an API drove the write.
 
-See sample: `xrec-is-a-before-image-only-in-some-triggers.good.al`.
+See sample: [`xrec-is-a-before-image-only-in-some-triggers.good.al`](xrec-is-a-before-image-only-in-some-triggers.good.al).
 
 ## Anti Pattern
 
@@ -33,4 +33,4 @@ Comparing `Rec` against `xRec` inside `OnModify` (or `OnInsert`) to detect a cha
 
 Detection signal: any read of `xRec` inside `OnModify` or `OnInsert`. Treat "but it works when I test it on the page" as confirmation of the defect rather than a refutation.
 
-See sample: `xrec-is-a-before-image-only-in-some-triggers.bad.al`.
+See sample: [`xrec-is-a-before-image-only-in-some-triggers.bad.al`](xrec-is-a-before-image-only-in-some-triggers.bad.al).