--- type: types/type-guidance.md name: source description: 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 --authority ` 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=` 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](../raw/CONTRACT.md#getting-a-file-in-incoming) - 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