Safari Reading List Wiki Home About Schema Log Sources

Docs

Schema

Safari Reading List Wiki Schema

Domain

A personal, compounding research corpus compiled from Gal's Safari Reading List. It preserves the whole Reading List as an immutable source layer, then turns recurring ideas into concise, navigable knowledge pages.

Source and Provenance Policy

  • Source kind: safari_reading_list only.
  • Source identity: Safari-native UUID where available; otherwise safari:url:<sha256-of-exact-url>. URL-hash identities deduplicate only inside Safari; they are never merged with X-bookmark records or another source.
  • The normalized snapshot in _meta/snapshots/ is the ingestion system of record.
  • raw/ is immutable after capture. Corrections and synthesis belong in wiki pages, never by rewriting a raw source.
  • A source that cannot be captured (paywall, 404, timeout, unsupported content) gets a clearly marked degraded raw record; it must not generate invented claims.
  • Replaying a byte-identical snapshot is idempotent: no duplicate observations, raws, or curator work.

Conventions

  • File names: lowercase, hyphenated, no spaces.
  • Every entity, concept, comparison, and query page begins with YAML frontmatter:

```yaml

title: Page Title created: YYYY-MM-DD updated: YYYY-MM-DD type: entity | concept | comparison | query | summary tags: [taxonomy-tags-only] sources: [raw/articles/source-file.md] confidence: high | medium | low contested: false

```

  • Use [[wikilinks]] for cross-references. Every newly created synthesis page must have at least two outbound links where there are two relevant pages to link.
  • On pages synthesizing three or more sources, append a provenance marker such as ^[raw/articles/source-file.md] to each source-derived paragraph.
  • Update a page's updated date when changing it.
  • Add every synthesis page to index.md and append every meaningful action to log.md.

Raw Article Format

---
source_url: https://example.com/article
source_key: safari:url:<sha256>
title: Source title
author: ""
added_at: YYYY-MM-DD
captured_at: YYYY-MM-DDTHH:MM:SSZ
capture_status: captured | degraded
content_sha256: <sha256 of exact body below frontmatter>
---

Delegated Extraction and Assembly

  • Mechanical per-source extraction lives in _meta/extractions/chunk-*.json; each record preserves the exact source_key and raw_path it analyzed.
  • Extraction records may be complete or insufficient_source. The latter is retained for inventory/provenance but cannot support a synthesized factual claim unless a captured source later supplies sufficient evidence.
  • _meta/extraction-chunks/ declares expected source-key, raw-path, and body-hash coverage before a delegated worker starts. It is not a knowledge layer.
  • scripts/validate_extractions.py verifies exact coverage, raw-body SHA-256 consistency, and output-shape limits; scripts/assemble_corpus.py --require-complete refuses a global corpus until every manifest record has a validated extraction.
  • The final corpus artifact is build metadata, not a substitute for raw citation: every synthesis page still cites concrete paths under raw/articles/.

Source-to-Synthesis Routing

  • _meta/source-routing.json is the exact, human-auditable routing inventory for every complete corpus record.
  • Each complete source has exactly one disposition: synthesized, naming one or more substantive pages that cite its raw path, or source-only, naming no page and giving a nonempty editorial rationale.
  • source-only is a narrow preservation outcome for material that does not yet form a reusable knowledge node. It is not an excuse to omit a source silently.
  • scripts/lint_wiki.py fails closed on missing, malformed, duplicate, unexpected, uncited, or unrouted complete-source entries.

Tag Taxonomy

  • ai-agents
  • ai-safety
  • career-work
  • corpus-navigation
  • data-systems
  • developer-workflow
  • digital-media
  • finance-markets
  • machine-learning
  • photography
  • security-privacy
  • software-engineering
  • web-infrastructure

These thirteen tags are corpus-derived, intentionally broad, and are the only tags available to synthesis pages. Fine-grained source labels remain in the immutable extraction artifacts rather than becoming a second, sprawling page taxonomy.

Page Thresholds

  • Create a page when a concept/entity occurs in two or more captured sources, or is central to one especially substantial source.
  • Update an existing page rather than create a duplicate.
  • Do not create pages for passing mentions, minor details, or isolated clickbait.
  • Create comparisons only where the corpus supports a genuine side-by-side analysis.
  • Split pages over about 200 lines.

Update and Contradiction Policy

  1. Prefer newer, better-supported sources when resolving ordinary factual updates.
  2. When sources genuinely conflict, preserve both dated positions, mark contested: true, and list any related page in contradictions: frontmatter.
  3. Single-source, opinion-heavy, or degraded-source claims start at medium or low confidence; high confidence requires corroboration.