ruff skill

docs/architecture.md

@@ -124,7 +124,7 @@ Repository indexing metadata is declared in `x-personal-mcp`:
 3. tags
 4. capabilities
 5. depends_on
-6. references map (ref id to relative path and optional metadata)
+6. optional references map (for nested entries, overrides, and aliases)
 
 No `metadata.yaml` sidecar is part of the end-state contract.
 
@@ -143,7 +143,9 @@ For the full URI semantics, parameter validation rules, and compatibility policy
 Validation rules:
 
 1. `skill_id` is lowercase kebab-case and must satisfy the stable skill id contract.
-2. `ref_id` is lowercase kebab-case and must be declared in the skill references manifest.
+2. `ref_id` is lowercase kebab-case and must resolve from either:
+    - top-level auto-discovery of `references/*.md` filename stems, or
+    - an explicit `x-personal-mcp.references` entry.
 3. `path*` resolves only to normalized markdown paths under `docs/`.
 
 ### Resource Registration Contract