chemenu/types/source.guidance.md

type, name, description

type	name	description
types/type-guidance.md	source	When to write a source page instead of a neighboring type, and how to write a conforming one - capture-field, provenance and not-extracted rules that hold regardless of which source_type values this instance chose

Source Guidance

source is the type for pages that summarize and catalogue ingested raw material. Source pages are the bridge between the raw/ layer (immutable source files) and the kb/ layer (compiled knowledge). One source page stands for one logical source, which may span several raw files.

When to use

• Summarizing a single external article, document or specification
• Recording several related notes or meeting records as one source
• Documenting an ingested PDF, manual or other document
• Capturing information about an image or a diagram

When NOT to use

• For compiled knowledge (use entity or concept)
• For comparative analyses (use comparison)
• For original wiki content not derived from raw material

Authoring guidance

• source_type has no default - wikitool new source refuses without an explicit value. Where the category is unclear, set unclassified rather than guessing; that is a visible catalog slot with an advisory lint finding, not a dumping ground. What separates analysis from document, and which area holds which value, is a call this instance's own collection contract makes - see kb/sources/COLLECTION.md
• raw_files lists every raw file this source covers (one source page per logical source, not per file)
• fidelity and authority are capture fields (capture_fields: on this type): recorded at the drop point and not freely changeable afterwards. wikitool raw accept --fidelity <value> --authority <value> refuses without both; without --page it instead prints the ready-made new source --set fidelity=... --set authority=... line, which new source in turn refuses without both values. wikitool touch --set fidelity=<value> only writes while the field is absent - where a value already stands, it refuses and points at raw accept --replaces as the one correction path (a corrected capture is a new edition, not an edit). unknown is backfill-only: only wikitool touch may write it, never raw accept or new source - the same construction as source_language uses for pages that predate this rule. What the values mean and how they differ: raw/CONTRACT.md
• For external articles, always set source_url to the origin URL
• Set source_language to the raw material's language, not the page's
• The page is written in the KB language, whatever language the source is in; verbatim passages are quoted in the original (kb/CONVENTIONS.md § "Language")
• Summarize the key claims in the summary section
• Put anything actionable in the action items section
• Put deliberate omissions in the not-extracted section - see below
• Link the entities and concepts mentioned under related entities/concepts

Not Extracted

The decision that material should not be taken over cannot be reconstructed: nothing in the repository can re-derive it, and sources coverage only knows whether a raw file is claimed by some source page - never whether anyone decided about its contents. Left unwritten, the same source is renegotiated on every later pass.

• Record every deliberate omission with a reason, not just a filename.
• Mandatory where the ingest ran through instructions/ingest-large-tree.md - on both axes: for a tree ingest the section records what was not taken from the tree; for a thematically broad single source, which named subjects got no page of their own, and why. Optional for a single small file - but an empty section still beats a missing one.
• Belongs on the source page, not in kb/log.md: it is a statement about this source, and the log is chronological rather than per-source.

---

Relevant Notes:

• Source pages are the authoritative catalogue of what raw material has been ingested
• One raw file, one owner. A raw file appears in exactly one raw_files: - that page is responsible for keeping it summarized. Any number of pages may cite it via [^cite-id]; a citation is reuse, raw_files: is a maintenance responsibility. With two claimants it is undefined which page has to be brought up to date when the raw file changes - and then both rot quietly
• Source pages make knowledge traceable back to the original raw material
• raw_files: holds concrete existing file paths, never directories
• A raw_files: list beyond roughly 15 entries indicates the cut was too coarse - the source should have been split into several source pages via instructions/ingest-large-tree.md
• entities: plus concepts: beyond roughly 20 entries is the counterpart on the other axis: not cut too little, but compiled too much at once. Such a source is not split - a raw file has one owner - it needed the extract pass from instructions/ingest-large-tree.md § "A broad source is not cut", so that not every named subject gets a page