Field Notes

meta

Source and evidence model

StatusStableUpdatedSupportsnotes

The wiki treats evidence as immutable and interpretation as the wiki’s own work. This separation is the architectural spine: sources are foreign transactions, while concepts, entities, and syntheses are the vault’s ledger, holding its own checked interpretation of what the sources say.

Immutable evidence under src/sources/

src/sources/ contains the raw evidence: PDFs, saved web pages, transcripts, exports, and raw intake. It may contain non-Markdown files and subdirectories. This directory is immutable after import: do not clean up, rewrite, or summarize raw evidence in place.

The sole exception is creating the raw and rendered HTML pair during import — see below.

Source notes

A type: source note in src/ describes one immutable artifact under src/sources/. It records:

  • What the artifact is (a saved web page, a PDF report, a transcript, an export).
  • Where it came from (the original URL, citation, or accession details).
  • What it supports (which subjects in the wiki it bears on).
  • A link to the local artifact using a source-document-relative path such as sources/example.pdf.

Source notes are the wiki’s provenance layer. They anchor claims to durable, revisitable evidence without reproducing the source’s argument.

The raw and rendered HTML pair

For web pages imported via just download, the import creates two files:

  • A .raw.html file: the exact server response, the provenance copy.
  • A .html file: a script-free browser-rendered snapshot with a <base> element pointing to its final source URL.

The rendered snapshot is what readers see. The raw file is what an audit can verify. Both live under src/sources/ and are immutable after creation.

The import workflow

When the user provides a bare link with no other instruction, the default action is to import it as a source. The workflow:

  1. Load .agents/skills/import-source/SKILL.md.
  2. Download or preserve a durable copy under src/sources/. Use a dated, descriptive, Windows-safe filename.
  3. For HTML pages, use just download "URL" "YYYY-MM-DD-descriptive-name.html".
  4. For YouTube videos, save the timestamped transcript rather than the plain transcript, along with the video’s title, uploader, and upload date.
  5. Create or update a type: source note in src/.
  6. Run the placement pass: search the vault for every subject the source bears on and decide, per subject, whether to update an existing note, create a new note, or record that the source does not yet connect to anything grounded.

The placement pass

An imported source that changes nothing is filing, not knowledge. The placement pass searches the vault for every subject the source bears on and decides per subject:

  • Update an existing note with new evidence or claims.
  • Create a new concept, entity, question, or synthesis note grounded in the source.
  • Record that the source does not yet connect to anything grounded — a legitimate conclusion, but one reached deliberately, not by stopping at the source note by default.

Evidence flows downward

The dependency graph runs from sources upward:

flowchart TD
  source@{ shape: cyl, label: "source" }
  concept@{ shape: rounded, label: "concept" }
  entity@{ shape: hex, label: "entity" }
  synthesis@{ shape: subproc, label: "synthesis" }

  source --> concept
  source --> entity
  concept --> synthesis
  entity --> synthesis

Solid edges carry evidence. Concepts and entities extract checked interpretations from sources; syntheses argue conclusions from concepts and entities. Direct citation is allowed as an escape valve, but centralization through concepts is preferred for claims reused across notes because it creates a single interpretation site: one fix that propagates, rather than a divergence invisible until someone compares syntheses.

Why immutability matters

Immutability serves three purposes:

  1. Auditability. A claim in a synthesis can be traced back to the exact evidence it rests on, and that evidence can be re-read years later.
  2. Review. just review and review_after assume the underlying evidence is stable. If sources could be silently rewritten, claim revalidation would be meaningless.
  3. Concurrency. Multiple agents can edit wiki notes in parallel without stepping on each other’s evidence. The immutable boundary prevents one session’s edit from destroying another session’s source material.

This note cites no sources of its own.

Working out connections…