#664 Tolerate unknown keys in .agents/preferences.yaml

packages/agents/content/skills/_data/artifact-conventions.md

@@ -69,6 +69,14 @@ For contexts where neither the deriver nor a cached manifest is available (e.g.,
 4. If `base_dir` is relative, resolve from project root. If absolute, use as-is.
 5. Read `project.slug` from `.agents/preferences.yaml`, falling back to `~/.agents/preferences.yaml`, then the bare directory name of the working directory.
 
+### Reader tolerance and authoring-time validation
+
+The session-context deriver reads only the fields it consumes (`artifacts.base_dir`, `artifacts.paths`, `project.slug`, `project.ticket_ref_prefix`, `platform`, `repository.slug`, `repository.default_remote.{name,default_branch}`). Unknown top-level keys, unknown nested keys, and keys for other tooling that shares `.agents/preferences.yaml` are silently tolerated — this file is a multi-tool surface (analogous to `.editorconfig` or `package.json`), not a codeassembly-owned namespace.
+
+Schema validation against `schemas/preferences.json` is an authoring-time concern, surfaced by the `$schema` reference at the top of the YAML (for editor LSPs) and by `preferences-schema.test.ts` against the project-checked-in `.agents/preferences.yaml`. The reader does not validate against the schema at runtime; doing so would fail on legitimate keys owned by other tools.
+
+The reader does still hard-fail on malformed YAML, missing git state, and shape problems on fields it consumes (e.g., `artifacts.base_dir` set to a non-string, `platform` set to a value outside the `github | bitbucket` enum). Per-field errors name the offending key path so the user can locate the issue without reading the whole file.
+
 ### Ticket-scoped paths
 
 ```