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
• Put what was read from a page image in a section of its own - see Page images 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.

Page images

What a model read from a page image of original.pdf (instructions/read-page-images.md) is not text the tool derived, and it is not the source's own wording: it is a reading. It gets its own section on the source page, headed in the KB language (a German instance: Am Seitenbild gelesen), so a reader can tell it from the summary.

• One entry per statement, with the page. Each entry names the page number and says that it was read from the page image, so it is checked against that page and not against derived.md.
• Name the intermediary. Where a subagent did the reading, the entry says so; the provenance chain then has its middle party visible (instructions/capture-session.md calls that second-hand).
• Cite it as the original. Another page that takes over a statement from this section cites it with cite add --file original.pdf; text taken from the derivation is cited with --file derived.md. The two files are one source with two readings, and the qualifier is what tells them apart.
• Hedge as the reading deserves (kb/CONVENTIONS.md § Hedging): a label that could not be read with certainty is written as uncertain, not completed.
• Pages not read stay visible. A selected page nobody looked at, with the reason, goes into the not-extracted section.

---

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