resource-provenance

Resource provenance

Every file under resources/ carries YAML frontmatter documenting where it came from. The frontmatter IS the index — there is no separate manifest file.

Two namespaces

• resources/fetched/ — immutable third-party sources (web pages, PDFs, articles, datasets). Do not overwrite after first save; if you need a newer version, save it as a new file.
• resources/generated/ — content you authored as part of a task.

Never mix the two. Never write generated content into fetched/. Never overwrite a fetched file.

Required frontmatter

For resources/fetched/

---
source: <URL or other origin identifier>
fetched_at: <ISO 8601 timestamp, e.g. 2026-04-19T14:22:00Z>
fetched_by: <vault-relative path to the job folder, e.g. jobs/2026-04-19-plan-kyoto-trip, OR the literal string "light" if fetched during a Light-tier request>
---

For resources/generated/

---
generated_by: <vault-relative path to the job folder>
generated_at: <ISO 8601 timestamp>
purpose: <single-line human description>
---

Binary files

If the format cannot host inline frontmatter (PDFs, images, audio, binary data), write a sibling file <name>.meta.yaml containing the same fields. Example:

resources/fetched/
├── kyoto-guidebook.pdf
└── kyoto-guidebook.pdf.meta.yaml

Naming

Use descriptive, content-derived filenames — same philosophy as memory. Avoid doc1.pdf, page.html, output.md. Prefer kyoto-lonelyplanet-2025.html, itinerary-v1.md, gion-restaurants-with-reservations.md.

Directory shape per job

Generated files for a job typically cluster:

resources/generated/
└── 2026-04-19-plan-kyoto-trip/
    ├── itinerary-v1.md
    ├── itinerary-v2.md
    └── lodging-shortlist.md

A per-job subfolder is optional; flat placement directly under resources/generated/ is also fine. Either way, frontmatter's generated_by is the source of truth for attribution.

Linking from jobs

In plan.md's Tasks section, link each generated artifact from the task that produced it:

- [x] 3. Draft the itinerary v1
  - resources/generated/2026-04-19-plan-kyoto-trip/itinerary-v1.md

Discovery

To find resources, use ls / glob over resources/fetched/ or resources/generated/ and read frontmatter as needed. Obsidian's graph view also renders these connections.

Do NOT create a resources/index.md. An index is a derived cache that drifts — frontmatter is authoritative.

Guardrails

• Every resource file gets frontmatter. No exceptions. Binary → sibling .meta.yaml.
• Fetched is immutable. New version? New file.
• fetched_by is a job path or the string light. Never blank, never a free-text description.
• No resources/index.md. Frontmatter is the index.
• No nested ambiguity between fetched and generated. A file is one or the other; the directory determines which.