/wiki-ingest

name: wiki-ingest
description: Use when adding a new source to a wiki — a paper, article, URL, file, transcript, or any document. One ingest may touch 10-15 wiki pages.

Wiki Ingest

Add a source to the wiki. Read it, discuss with the user, write a summary page, update entity/concept pages, and maintain the index, overview, and log.

Pre-condition

Search for `SCHEMA.md` starting from the current directory and upward, or in common wiki locations (`~/wikis/`). If not found, tell the user to run `wiki-init` first.

Read `SCHEMA.md` to learn: wiki root path, page frontmatter format, cross-reference convention, log entry format, index category taxonomy.

**Link style.** Read `link_style:` from `SCHEMA.md`. If the field is missing or `<wiki-root>/config/link-style.md` does not exist, default to `obsidian` and use `[[slug]]` as the cross-reference form. Otherwise, read `<wiki-root>/config/link-style.md` for the exact emit and parse rules. Every cross-reference and citation slug-target you write below must follow that file's `## Emit` rule. Every scan of existing pages (the backlink audit in step 7) must follow its `## Parse` rule.

Process

1. Accept the source

The source can be:

• **File path** — read it directly; copy to `raw/<filename>` if not already there
• **URL** — use the `browse` skill to fetch it; save to `raw/<slug>.<ext>`
• **Pasted text** — use what was provided

2. Read the source in full

Read all content. For long sources, read in sections. Do not skip.

3. Surface takeaways — BEFORE writing anything

Tell the user:

• 3-5 bullet points of key takeaways
• What entities/concepts this introduces or updates
• Whether it contradicts anything already in the wiki (regenerate the index first — `python bin/generate-index.py` — then read `wiki/index.md` and relevant pages to check)

Ask: **"Anything specific you want me to emphasize or de-emphasize?"**

Wait for the user's response before proceeding.

4. Generate the slug

Lowercase, hyphens, no special characters. Example: "Attention Is All You Need" → `attention-is-all-you-need`

5. Write the source summary page

Write `wiki/pages/<slug>.md`:

---
title: <source title>
category: <one of the wiki's Index Categories — e.g. Sources>
summary: <one-line description for the index>
tags: [<relevant tags>]
sources: [<slug>]
created: <today>
updated: <today>
---

# <Source Title>

**Source:** <original URL or file path>
**Date ingested:** <today>
**Type:** <paper | article | transcript | code | other>

## Summary

<2-3 paragraph synthesis — your own words, not abstract copy-paste>

## Key Takeaways

- <bullet>

## Entities & Concepts

<list of entities/concepts as cross-reference links — emit each in the wiki's link_style; see config/link-style.md>

## Relation to Other Wiki Pages

<how this connects to or updates existing knowledge>

5b. Cite as you write — do not skip

While drafting the Summary, Key Takeaways, and any other prose section, every non-common-knowledge factual claim must carry a footnote. Read the **Citations** section in `SCHEMA.md` for the full convention.

Two citation kinds, three valid targets:

Quote:     [^N]: <target> <locator> — "<verbatim quote>"
Synthesis: [^N]: <target> <locator> [synthesis] — <what supports the claim>

<target> is one of:
  <slug-reference>     — a source wiki page, written in the wiki's link_style
                         (preferred for the source you're ingesting)
  raw/<file>           — a path, for drive-by citations to other local files
  <URL>                — a live URL or post

For the source being ingested, the slug-reference target is `<this-source-slug>` written in the form prescribed by `config/link-style.md`. `wiki-ingest` is creating that page now, so the target exists by the time the page is read.

**Line-range provenance — required for text-addressable sources.** If the raw file you are citing is markdown, plaintext, code, or cached HTML, every footnote to it must carry a line-range token after the semantic locator: `L<start>-<end>` (or `L<n>` for a single line). As you read the raw file, note the line numbers of the passage you are citing — for a quote, the lines the quote is taken from; for a `[synthesis]` claim, the block of lines being summarized. Example:

[^1]: [[<this-source-slug>]] §3.2 L142-143 — "We employ h = 8 parallel attention layers"
[^2]: [[<this-source-slug>]] §3.2-5.3 [synthesis] L138-202 — encoder/decoder + attention describe the architecture

Sources WITHOUT stable line numbers — PDFs, transcripts, and live URLs with no local cached copy — are exempt: keep the semantic locator (`p.N`, `[HH:MM:SS]`, URL anchor) and omit `L…`.

If you cannot produce either citation kind for a claim, you do not have a citation. Find one, weaken the claim ("the paper suggests..."), or drop it.

Footnotes go at the bottom of the page, below all sections. Number them sequentially in order of first reference.

5c. Self-check before continuing

Re-read the draft once. Three passes:

1. **Unfootnoted claims** — scan for factual claims with no footnote (the most common failure mode in long ingest sessions). For each, add a footnote or revise the wording. 2. **Missing line-ranges** — for every footnote whose target is a text-addressable raw file (markdown / plaintext / code / cached HTML), confirm an `L…` token is present. A text-source footnote with no line-range is incomplete: go back to the raw file, find the lines, and add the token. Exempt sources (PDF / transcript / live URL) are fine without one. 3. **Link resolution** — collect every `[[slug]]` you wrote in this page and confirm each resolves to an existing `wiki/pages/<slug>.md` or to a page you are creating in this same ingest. See the **Concept Identity** rule in `SCHEMA.md`. Any `[[slug]]` that resolves to neither is a hallucinated link: remove it, or create the page it points to. This is the inline version of the broken-link c