Resolve v3 minimal vault install DX gaps

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

Author: jrcruciani

examples/v3-minimal-vault/README.md

@@ -100,10 +100,34 @@ valid_to: null
 
 Every referenced entity must appear in `memory/entities.md`. This is strict because typos in entity IDs silently split memory.
 
-> **Common mistakes**
->
-> - `sources:` entries are local filesystem paths relative to the vault. To cite an external URL, put it in the note body or save a local source file under `sources/articles/` and cite that file.
-> - New fact predicates must be declared in `memory/schema/predicates.yaml` before facts use them.
+### Common mistakes lint will catch
+
+A short field guide to first-contact errors and how to fix them:
+
+- **`source does not exist: https://...`** — `sources:` entries are local filesystem paths relative to the vault root, not URLs. To cite an external URL, put it in the note body or save a local source file under `sources/articles/` and cite that path.
+- **`missing required field 'recorded_at'`** — every `fact` needs an ISO-8601 timestamp for when the fact was recorded. `valid_from` is separate and optional.
+
+  ```yaml
+  type: fact
+  entity: elena-voss
+  predicate: role
+  value: "Art conservator"
+  recorded_at: 2026-05-13T18:51:00Z
+  valid_from: 2026-05-13
+  valid_to: null
+  confidence: high
+  sources: []
+  ```
+
+- **`unknown predicate 'X'`** — predicates are controlled by `memory/schema/predicates.yaml`. Declare the predicate before writing facts or operation payloads that use it.
+
+  ```yaml
+  predicates:
+    - id: spec-version
+      description: Declared spec version of a memory vault or schema.
+  ```
+
+- **`source:` vs `sources:`** — the schema field is the plural array `sources: []`, not the singular `source:`.
 
 ### Narrative note schemas
 

examples/v3-minimal-vault/tools/lint.py

@@ -27,6 +27,7 @@
 HASH_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
 SUPPORTED_SPEC_VERSION = "3.0"
 PREDICATE_HINT = "add it to memory/schema/predicates.yaml"
+SOURCE_HINT = "sources: items must be filesystem paths relative to the vault root, not URLs"
 
 
 class Finding:
@@ -118,6 +119,10 @@ def unknown_predicate_message(predicate: Any, prefix: str = "unknown predicate")
     return f"{prefix} {predicate!r} -- {PREDICATE_HINT}"
 
 
+def missing_source_message(source: Any, prefix: str = "source does not exist") -> str:
+    return f"{prefix}: {source} -- {SOURCE_HINT}"
+
+
 def validate_type(value: Any, expected: Any) -> bool:
     if isinstance(expected, list):
         return any(validate_type(value, item) for item in expected)
@@ -297,7 +302,7 @@ def validate_operation_payload(
             findings.append(Finding("ERROR", path, f"payload: {exc}"))
         for source in payload.get("sources", []) or []:
             if not (root / source).exists():
-                findings.append(Finding("ERROR", path, f"payload source does not exist: {source}"))
+                findings.append(Finding("ERROR", path, missing_source_message(source, "payload source does not exist")))
 
     if op == "add_event":
         if payload_type != "event":
@@ -307,7 +312,7 @@ def validate_operation_payload(
                 findings.append(Finding("ERROR", path, f"payload unknown event entity {entity!r}"))
         for source in payload.get("sources", []) or []:
             if not (root / source).exists():
-                findings.append(Finding("ERROR", path, f"payload source does not exist: {source}"))
+                findings.append(Finding("ERROR", path, missing_source_message(source, "payload source does not exist")))
 
     return findings
 
@@ -376,7 +381,7 @@ def validate(root: Path) -> list[Finding]:
                     findings.append(Finding("ERROR", path, f"superseded_by target does not exist: {superseded_by}"))
             for source in data.get("sources", []) or []:
                 if not (root / source).exists():
-                    findings.append(Finding("ERROR", path, f"source does not exist: {source}"))
+                    findings.append(Finding("ERROR", path, missing_source_message(source)))
 
         if typ == "event":
             for entity in data.get("entities", []) or []:
@@ -391,7 +396,7 @@ def validate(root: Path) -> list[Finding]:
                 findings.append(Finding("ERROR", path, str(exc)))
             for source in data.get("sources", []) or []:
                 if not (root / source).exists():
-                    findings.append(Finding("ERROR", path, f"source does not exist: {source}"))
+                    findings.append(Finding("ERROR", path, missing_source_message(source)))
             for derived in data.get("derived_facts", []) or []:
                 if not (root / derived).exists():
                     findings.append(Finding("ERROR", path, f"derived fact does not exist: {derived}"))
@@ -414,7 +419,7 @@ def validate(root: Path) -> list[Finding]:
                 findings.append(Finding("ERROR", path, "target_path must be a relative path without '..'"))
             for source in data.get("sources", []) or []:
                 if not (root / source).exists():
-                    findings.append(Finding("ERROR", path, f"source does not exist: {source}"))
+                    findings.append(Finding("ERROR", path, missing_source_message(source)))
             findings.extend(validate_operation_payload(root, path, data, schemas, entities, predicates))
 
         if typ in {"decision", "insight"}:
@@ -423,7 +428,7 @@ def validate(root: Path) -> list[Finding]:
                     findings.append(Finding("ERROR", path, f"unknown {typ} entity {entity!r}"))
             for source in data.get("sources", []) or []:
                 if not (root / source).exists():
-                    findings.append(Finding("ERROR", path, f"source does not exist: {source}"))
+                    findings.append(Finding("ERROR", path, missing_source_message(source)))
 
         if typ == "entity-index":
             for item in data.get("entities", []) or []: