lumina-wiki 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -5,6 +5,57 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [1.7.2] - 2026-07-05
+
+### Fixed
+
+- `/lumi-ingest` step-03-verify referenced `src/skills/core/verify/` — the
+  repo source tree — instead of the installed workspace path. On any
+  non-Claude-Code IDE target (Codex, Gemini, Cursor, generic), the file
+  never existed post-install, so grounding verification silently had
+  nothing to follow. Fixed all three references to
+  `.agents/skills/lumi-verify/`, which the installer copies unconditionally
+  for every IDE target.
+- Added an `ingest_status` handler for the `not_applicable` verify verdict,
+  which was previously unhandled during ingest.
+
+### Added
+
+- `/lumi-ingest` now checks external identifiers (DOI/arxiv/S2) for an
+  existing source page before generating a slug, so the same paper
+  ingested under a different title no longer creates a duplicate page.
+- Concept stub creation now scans existing concepts for acronym/expansion
+  and singular/plural variants before creating a new one.
+- Key Claims in drafted source pages now require a source locator
+  (section/page/heading), so the grounding reviewer in step-03 no longer
+  has to re-scan the whole raw file to check a claim.
+- A concept-count rubric (roughly 3-7 per source) to keep the graph from
+  being diluted by over-extracted keyword stubs.
+- PDF preprocessing now runs before type detection in step-01, so runtimes
+  without native PDF reading don't fail attempting to read the raw binary.
+
+## [1.7.1] - 2026-07-02
+
+### Added
+
+- `wiki.mjs init --pack learning` now creates `wiki/reflections/`, matching the
+  learning pack's entity schema. Valid `--pack` values are derived from the
+  schema instead of hardcoded, so future packs stay in sync automatically.
+
+### Fixed
+
+- `/lumi-research-topic` previously failed every `add-edge` call with "Unknown
+  edge type" because the topic-organization edges it relies on
+  (`includes_source`/`included_in_topic`, `covers_concept`/`covered_by_topic`)
+  were missing from the schema. Added all four to `EDGE_TYPES`.
+- Corrected skill-prompt and documentation drift: the reset skill's dry-run
+  output format, the internal lint-check reference table (was missing
+  L10-L12), and the documented behavior of ingest phase checkpoints (keyed
+  by file basename, not slug, since the checkpoint exists before slug
+  generation; the checkpoint JSON's `slug` field, written once the slug
+  phase completes, is now documented as the way other skills match a
+  checkpoint to its wiki entry).
+
 ## [1.7.0] - 2026-06-16
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "lumina-wiki",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",

package/src/scripts/schemas.mjs

@@ -215,6 +215,12 @@ export const EDGE_TYPES = [
   { name: 'part_of',            from: 'concepts', to: 'concepts', reverse: 'has_part',        symmetric: false, pack: 'core' },
   { name: 'has_part',           from: 'concepts', to: 'concepts', reverse: 'part_of',         symmetric: false, pack: 'core' },
 
+  // --- research pack: topic organization edges -----------------------------
+  { name: 'includes_source',    from: 'topics',   to: 'sources',  reverse: 'included_in_topic', symmetric: false, pack: 'research' },
+  { name: 'included_in_topic',  from: 'sources',  to: 'topics',   reverse: 'includes_source',   symmetric: false, pack: 'research' },
+  { name: 'covers_concept',     from: 'topics',   to: 'concepts', reverse: 'covered_by_topic',  symmetric: false, pack: 'research' },
+  { name: 'covered_by_topic',   from: 'concepts', to: 'topics',   reverse: 'covers_concept',    symmetric: false, pack: 'research' },
+
   // --- terminal edges (no reverse) — exempt-only rule applies -------------
   // Any entity -> foundations/** (research pack)
   { name: 'grounded_in',        from: '*', to: 'foundations', reverse: null, terminal: true, pack: 'research' },

package/src/scripts/wiki.mjs

@@ -1179,26 +1179,33 @@ const CORE_WIKI_DIRS = [
   'wiki/graph',
 ];
 
-/** Research pack additional wiki dirs */
-const RESEARCH_WIKI_DIRS = [
-  'wiki/foundations',
-  'wiki/topics',
-];
+/**
+ * Installable (non-core) pack names, derived from ENTITY_DIRS so a new pack
+ * added to schemas.mjs becomes selectable via `init --pack` without touching
+ * this file.
+ * @type {string[]}
+ */
+const INSTALLABLE_PACKS = [...new Set(Object.values(ENTITY_DIRS).map(e => e.pack))]
+  .filter(pack => pack !== 'core');
 
-/** Reading pack additional wiki dirs */
-const READING_WIKI_DIRS = [
-  'wiki/chapters',
-  'wiki/characters',
-  'wiki/themes',
-  'wiki/plot',
-];
+/**
+ * Additional wiki dirs owned by a given pack, derived from ENTITY_DIRS.
+ * Preserves ENTITY_DIRS declaration order.
+ * @param {string} pack
+ * @returns {string[]}
+ */
+function wikiDirsForPack(pack) {
+  return Object.values(ENTITY_DIRS)
+    .filter(e => e.pack === pack)
+    .map(e => `wiki/${e.dir}`.replace(/\/$/, ''));
+}
 
 /**
  * Initialize a workspace skeleton.
  * Idempotent: re-running on an existing workspace is a no-op.
  * @param {string} projectRoot
  * @param {object} [opts]
- * @param {string} [opts.pack] - 'research' | 'reading' | undefined
+ * @param {string} [opts.pack] - one of INSTALLABLE_PACKS | undefined
  * @returns {Promise<{created: string[], skipped: string[]}>}
  */
 async function initWorkspace(projectRoot, opts = {}) {
@@ -1206,10 +1213,8 @@ async function initWorkspace(projectRoot, opts = {}) {
   const skipped = [];
 
   let dirs = [...CORE_WIKI_DIRS];
-  if (opts.pack === 'research') {
-    dirs = [...dirs, ...RESEARCH_WIKI_DIRS];
-  } else if (opts.pack === 'reading') {
-    dirs = [...dirs, ...READING_WIKI_DIRS];
+  if (opts.pack && INSTALLABLE_PACKS.includes(opts.pack)) {
+    dirs = [...dirs, ...wikiDirsForPack(opts.pack)];
   }
 
   // Add _lumina/_state dir
@@ -1506,7 +1511,7 @@ async function main(argv) {
       'Usage: node wiki.mjs <subcommand> [flags]',
       '',
       'Subcommands:',
-      '  init [--pack research|reading]  Create workspace skeleton',
+      `  init [--pack ${INSTALLABLE_PACKS.join('|')}]  Create workspace skeleton`,
       '  slug <title>                    Emit kebab-case slug',
       '  log <skill> <details...>        Append to wiki/log.md',
       '  read-meta <slug>                Read entity frontmatter as JSON',
@@ -1539,8 +1544,8 @@ async function main(argv) {
         // init does not require an existing workspace; it creates one
         const projectRoot = process.cwd();
         const pack = flags.pack && typeof flags.pack === 'string' ? flags.pack : undefined;
-        if (pack && pack !== 'research' && pack !== 'reading') {
-          emitError(`Invalid --pack value: ${pack}. Must be research or reading.`, 2);
+        if (pack && !INSTALLABLE_PACKS.includes(pack)) {
+          emitError(`Invalid --pack value: ${pack}. Must be one of: ${INSTALLABLE_PACKS.join(', ')}.`, 2);
           process.exit(2);
         }
         const result = await initWorkspace(projectRoot, { pack });

package/src/skills/core/ask/SKILL.md

@@ -127,6 +127,16 @@ Do not ingest the file yourself. The user decides whether to proceed.
 
 If the user asks to save the answer:
 
+First check whether the target page already exists:
+
+```bash
+node _lumina/scripts/wiki.mjs read-meta outputs/<slug>
+```
+
+Exit 0 means the page exists. If it does, ask the user whether to overwrite
+it or pick a new slug — do not silently overwrite. Exit 2 ("Entity not
+found") means the slug is free; proceed.
+
 Ask for confirmation before writing. Then write
 `wiki/outputs/<slug>.md` or `wiki/summary/<slug>.md` with:
 ```yaml
@@ -232,5 +242,6 @@ Before reporting done, verify:
 
 (a) Every cited page in the answer exists in `wiki/` (readable)
 (b) If a page was filed: `wiki/log.md` has a new `## [YYYY-MM-DD] ask | ...` entry
-(c) If a page was filed: running `/lumi-ask` again with the same question does not
-    create a second output page (confirm with user or check for existing slug)
+(c) If a page was filed: the Step 6 existence check (`read-meta outputs/<slug>`)
+    ran before writing, so running `/lumi-ask` again with the same question
+    does not silently create or overwrite a second output page

package/src/skills/core/check/SKILL.md

@@ -99,7 +99,9 @@ node _lumina/scripts/lint.mjs --fix --json
 
 The `--fix` pass:
 - Applies the supported auto-fixes listed in `references/lint-checks.md`
-- Leaves L02, L05, and L08 for manual correction
+  (L01, L03, L06, L07, L09)
+- Leaves every other check (L02, L04, L05, L08, L10, L11, L12, L13, L14, L16)
+  for manual correction
 
 ### Step 4 — Self-check re-run
 
@@ -117,8 +119,10 @@ If errors remain, do not report done. Address each remaining error specifically:
   ```bash
   node _lumina/scripts/wiki.mjs set-meta <slug> <key> "<value>"
   ```
-- If L02, L05, or L08 remain, report the exact fields, wikilinks, or edges that
-  need manual correction.
+- If L02, L05, L08, or L10 remain, report the exact fields, wikilinks, edges,
+  or alias conflicts that need manual correction.
+- If L13 or L16 persist, suggest `/lumi-migrate-legacy --backfill-ids` — these
+  are not fixed by `lint.mjs --fix`.
 
 Repeat until `summary.errors === 0`. Do not loop more than 3 times — if errors
 persist, surface them to the user as needing manual attention.
@@ -137,12 +141,12 @@ Present findings in a structured list. Group errors first, then warnings.
 Lint check: <scanned_files> files scanned
 
 Errors (N):
-  [L06] concepts/positional-encoding.md:18 — Missing reverse edge to sources/attention-revisited
-  [L05] summary/transformers-overview.md:42 — Broken link [[flash-decoding]] (page not found)
+  concepts/positional-encoding.md:18 — a return link is missing, pointing back to sources/attention-revisited (L06)
+  summary/transformers-overview.md:42 — a link points to a page that does not exist: [[flash-decoding]] (L05)
 
 Warnings (M, advisory):
-  [L04] concepts/rotary-embeddings.md — Orphan page (no inbound links)
-  [L09] wiki/index.md — Index catalog is stale
+  concepts/rotary-embeddings.md — this page has no inbound or outbound links yet (L04)
+  wiki/index.md — the page catalog is out of date (L09)
 
 Fixes available: L06, L09 (N total). Apply? [yes/no]
 ```

package/src/skills/core/check/references/lint-checks.md

@@ -14,8 +14,16 @@ output in `/lumi-check`.
 | L05 | Broken wikilink | error | No — user must correct or create target |
 | L06 | Missing reverse edge | error | Yes — writes the reverse edge |
 | L07 | Duplicate symmetric edge | warning | Yes — deduplicates |
-| L08 | Missing required confidence field | error | No — user must add confidence |
+| L08 | Missing required confidence field on an edge | error | No — user must add confidence |
 | L09 | Index out of sync | warning | Yes — rebuilds the index catalog |
+| L10 | Foundation alias conflict | error | No — user must rename or merge the colliding title/alias |
+| L11 | Missing `confidence` field on a source/concept page | warning | No — user must set a value |
+| L12 | `raw_paths` entry missing, unsafe, or parked in `raw/tmp/` | warning | No — user must move or fix the file, then update `raw_paths` |
+| L13 | `external_ids` missing a namespace derivable from `urls[]` | warning | No — run `/lumi-migrate-legacy --backfill-ids` |
+| L14 | `external_ids` value fails validation for its namespace | error | No — user must correct or remove the value |
+| L16 | `external_ids` value disagrees with the value derived from `urls[]` | warning | No — run `/lumi-migrate-legacy --backfill-ids` to reconcile |
+
+(L15 is intentionally unassigned — reserved for a future collision check.)
 
 ## Classification
 
@@ -26,13 +34,19 @@ Errors that must be resolved before done:
 - L03: non-kebab slugs
 - L05: broken wikilinks
 - L06: missing reverse edges
-- L08: missing required confidence fields
+- L08: missing required confidence field on an edge
+- L10: foundation alias conflicts
+- L14: invalid `external_ids` values
 
 Advisories to surface to the user:
 
 - L04: orphan pages
 - L07: duplicate symmetric edges
 - L09: index out of sync
+- L11: missing `confidence` on a source/concept page
+- L12: `raw_paths` missing, unsafe, or transient
+- L13: `external_ids` missing a derivable namespace
+- L16: `external_ids` disagrees with `urls[]`
 
 ## Fix Behavior
 
@@ -44,9 +58,11 @@ Advisories to surface to the user:
 - L07 deduplicates symmetric edges.
 - L09 regenerates the `<!-- lumina:index --> ... <!-- /lumina:index -->` block.
 
-L02, L05, and L08 require manual correction. If L06 remains after `--fix`, the
-target page may not exist; identify it and suggest `/lumi-ingest` or
-`/lumi-edit`.
+L02, L04, L05, L08, L10, L11, L12, L13, L14, and L16 require manual
+correction — none of them are touched by `--fix`. If L06 remains after
+`--fix`, the target page may not exist; identify it and suggest
+`/lumi-ingest` or `/lumi-edit`. For L13 and L16, the fix path is
+`/lumi-migrate-legacy --backfill-ids`, not `lint.mjs --fix`.
 
 The linter reads `_lumina/config/lumina.config.yaml` for exemption globs.
 `foundations/**`, `outputs/**`, and external URL targets are exempt from L06.

package/src/skills/core/edit/SKILL.md

@@ -123,6 +123,10 @@ manual follow-up.
 node _lumina/scripts/wiki.mjs log edit "Updated <slug>: <brief description>"
 ```
 
+After logging, suggest the user run `/lumi-check` in a fresh session or via a
+sub-agent. Blank context catches bias from the reasoning chain that just made
+this edit.
+
 ## Output Format
 
 Report to the user:
@@ -135,7 +139,7 @@ Example:
 Edited concepts/softmax-temperature.md:
 - Added definition paragraph in ## Overview
 - Linked back to sources/attention-revisited (used_in edge added)
-Lint: 0 errors, 1 warning (L04: orphan page — advisory)
+Links check out — one advisory note: this page has no inbound links yet (L04)
 ```
 
 ## Examples

package/src/skills/core/ingest/SKILL.md

@@ -58,7 +58,7 @@ This is the only logic in this body — everything else lives in step files. The
    | `drafted` | → `./references/step-02-lint.md` |
    | `linted` | → `./references/step-03-verify.md` |
    | `verified` | → `./references/step-04-finalize.md` |
-   | `finalized` | HALT, ask "this entry is already finalized; restart from scratch?" On `[Q]` (decline): exit cleanly, exit 0 — declining is not an error. On confirm, do these in order before re-entering step-01: (1) `set-meta sources/<slug> ingest_status drafted` (so a session crash mid-restart leaves the entry in a coherent stage, not a stale-finalized one), (2) delete the phase checkpoint at `_lumina/_state/ingest-<file-basename>.json`, (3) → `./references/step-01-draft.md`. |
+   | `finalized` | HALT, ask "this entry is already finalized; restart from scratch?" On `[Q]` (decline): exit cleanly, exit 0 — declining is not an error. On confirm, do these in order before re-entering step-01: (1) `set-meta sources/<slug> ingest_status drafted` (so a session crash mid-restart leaves the entry in a coherent stage, not a stale-finalized one), (2) delete the phase checkpoint at `_lumina/_state/ingest-<file-basename>.json` — at this point you may only know the slug, not the file basename, so derive it first: read `raw_paths[0]` via `read-meta sources/<slug>` and take its basename; if `raw_paths` is empty or unavailable, list `_lumina/_state/ingest-*.json` and read each one to find the checkpoint whose `slug` field equals `sources/<slug>`; if no checkpoint matches either way, there is nothing to delete — simply proceed, (3) → `./references/step-01-draft.md`. |
 
 ## Examples
 

package/src/skills/core/ingest/references/dedup-policy.md

@@ -3,6 +3,31 @@
 Use this reference before creating or updating source, concept, person, and graph
 records during `/lumi-ingest`.
 
+## Identifier Dedup (Before Slug Generation)
+
+Slug comparison alone misses duplicates: the same paper ingested under two title
+variants (with/without subtitle, arxiv version suffix, translated title) produces
+two different slugs. External identifiers are the stronger key, so check them
+first whenever one is known (from `resolve_pdf.py` output, or parsed from the
+input URL).
+
+```bash
+# One grep per known identifier, over source-page frontmatter.
+# Use the normalized value: bare DOI (10.x/y), bare arxiv id (2604.03501 — no version suffix).
+grep -rln "10.48550/arxiv.2604.03501" wiki/sources/
+grep -rln "2604.03501" wiki/sources/
+```
+
+- **Hit** — an existing page carries the same identifier. This run is a re-ingest
+  of that page's slug, regardless of what slug the current title would generate.
+  Confirm with the user, then follow the re-ingest path below; do not create a
+  second page.
+- **No hit** — proceed to slug generation.
+
+A plain substring grep is deliberate: identifiers are unique enough that false
+positives are rare, and a rare false positive only costs one confirmation
+question. A false negative (skipping the check) costs a duplicate source page.
+
 ## Source Pages
 
 Generate the source slug with:
@@ -47,7 +72,22 @@ making any `add-edge concepts/<slug>` calls.
 
 ## Concept And Person Stubs
 
-Before creating a concept or person page, check metadata:
+Exact-slug lookup only catches exact matches — `rlhf` and
+`reinforcement-learning-from-human-feedback` would become two pages. Once per
+ingest run, list the existing concepts and hold the list in mind while creating
+stubs:
+
+```bash
+node _lumina/scripts/wiki.mjs list-entities --type concept
+```
+
+For each candidate concept, scan that list for variants of the same term:
+acronym vs expansion, singular vs plural, hyphenation or word-order differences.
+If a variant exists, link to the existing slug instead of creating a new stub —
+and if unsure whether two terms are the same concept, ask the user rather than
+guessing.
+
+Then, before creating a concept or person page, check metadata:
 
 ```bash
 node _lumina/scripts/wiki.mjs read-meta concepts/<slug>

package/src/skills/core/ingest/references/step-01-draft.md

@@ -6,7 +6,7 @@
 - Never modify files in `raw/`. Read-only.
 - Never hand-edit `wiki/graph/edges.jsonl` or `wiki/graph/citations.jsonl`; use `wiki.mjs add-edge` and `wiki.mjs add-citation`.
 - Never overwrite an existing wiki page without user confirmation.
-- All frontmatter writes go through `wiki.mjs set-meta`. Never write to `wiki/*.md` directly. (Body text goes through Write tool atomically; finalizing frontmatter still uses `set-meta`.)
+- Frontmatter discipline, two cases: (a) **initial creation** of a page that does not exist yet — Write the whole file (frontmatter + body) in one shot from the template; (b) **any change to an existing page's frontmatter** — always `wiki.mjs set-meta`, never Write/Edit on the frontmatter block. Body text of an existing page may be edited with Write/Edit; the frontmatter block may not.
 - `raw/tmp/` accepts additions only; never overwrite a file there.
 - `raw_paths` must list permanent artifacts only. Reject `raw/tmp/*` entries.
 - Keep a phase-level checkpoint after every phase — an interrupted run must resume cleanly.
@@ -69,9 +69,13 @@ node _lumina/scripts/wiki.mjs checkpoint-read research-discover shortlist
 
 Match title to a shortlist entry, extract URL, fall through to Mode B.
 
+Fallback: if the checkpoint does not exist (research pack not installed, or no discover run yet) or no shortlist entry matches the title, do not guess. Ask the user for a URL or identifier (arxiv ID / DOI), then fall through to Mode B with their answer.
+
 ### Phase 1 — Detect type
 
-Read first ~200 lines of the source. Classify:
+If the source is a PDF or too large to read comfortably in one pass, follow `pdf-preprocessing.md` **before reading anything** — on runtimes without native PDF reading, a direct Read of the binary fails here, not in Phase 3.
+
+Read first ~200 lines of the source (or of the extracted text). Classify:
 - "Abstract", "Introduction", "References" → `paper`
 - Chapter structure → `book`
 - Web byline + publication → `article`
@@ -82,17 +86,34 @@ Write checkpoint: `phase: "detect"`.
 
 ### Phase 2 — Generate slug
 
+**Identifier dedup comes first.** If any external identifier is known at this point (DOI / arxiv ID / S2 ID — from Mode B resolution or parsed from the input URL), check for an existing source page carrying the same identifier BEFORE generating a slug — title variants produce different slugs, so slug comparison alone misses duplicates. See `dedup-policy.md` § Identifier Dedup. On a hit, this run is a re-ingest of the matched slug: confirm with the user and skip new-page creation.
+
 ```bash
 node _lumina/scripts/wiki.mjs slug "<Title>"
 ```
 
 If `wiki/sources/<slug>.md` already exists: re-ingest — confirm with user before overwriting.
 
-Write checkpoint: `phase: "slug"`.
+The phase checkpoint is keyed by file basename (`ingest-<file-basename>.json`)
+because it is written before the slug exists. Now that the slug is known,
+merge it into the checkpoint so later skills (e.g. `/lumi-migrate-legacy`) can
+match a checkpoint to a wiki entry by reading its content instead of guessing
+the filename:
+
+```bash
+# 1) Read current state
+node _lumina/scripts/wiki.mjs checkpoint-read ingest <file-basename>
+# 2) Merge {"phase":"slug","slug":"sources/<slug>","source_basename":"<file-basename>"}
+#    into the JSON above (preserve all other fields).
+# 3) Write back via stdin:
+echo '<merged-json>' | node _lumina/scripts/wiki.mjs checkpoint-write ingest <file-basename>
+```
+
+Write checkpoint: `phase: "slug"` (already included in the merge above).
 
 ### Phase 3 — Write source page
 
-For PDFs / large sources, follow `pdf-preprocessing.md` first.
+For PDFs / large sources, the extraction from Phase 1 (`pdf-preprocessing.md`) applies here too — draft from the extracted text, section by section for long sources.
 
 Draft `wiki/sources/<slug>.md` from `_lumina/schema/page-templates.md` Source template. Required frontmatter: `id`, `title`, `type`, `created`, `updated`, `authors`, `year`, `importance`, `provenance`. Optional but encouraged: `urls`, `raw_paths`, `confidence`, `external_ids`.
 
@@ -116,6 +137,10 @@ node _lumina/scripts/wiki.mjs set-meta sources/<slug> sources "[$entry]" --json-
 
 Required body sections: `## Summary` (2–4 sentences), `## Key Claims` (bulleted, with confidence), `## Concepts` (`[[concept-slug]]` links), `## People` (`[[person-slug]]` links), `## Open Questions`.
 
+`## Key Claims` — each claim ends with a locator pointing at where the source supports it: a section anchor, page, or heading, e.g. `(§3.2)`, `(p. 5)`, `(Table 1)`. The grounding check in step-03 reads these locators to find evidence; a claim without one forces the reviewer to re-read the whole raw file and weakens the check. If a claim synthesizes multiple places, list the primary locator.
+
+`## Concepts` — be selective, not exhaustive. A term earns a concept link only if (a) it is central to this source's contribution, or (b) it is likely to recur across other sources in this wiki. Aim for roughly 3–7 concepts per source; minor keywords belong in body prose, not as concept links. Every linked concept implies a stub + edges in Phases 4–5, so over-extraction dilutes the graph.
+
 Provenance rubric (raw-centric):
 - `replayable` — `raw_paths` non-empty, every entry resolves to existing file
 - `partial` — `urls` has entries but `raw_paths` empty or missing
@@ -141,7 +166,7 @@ node _lumina/scripts/wiki.mjs resolve-alias "<concept-name>"
 
 If it resolves to a foundation, link via `[[foundations/<slug>]]` and add `grounded_in` edge instead of creating a stub. See `dedup-policy.md` § Foundation Resolution.
 
-Apply `dedup-policy.md` before creating/updating stubs. Existing pages are updated conservatively.
+Apply `dedup-policy.md` before creating/updating stubs — including the concept variant scan (acronym vs expansion, singular vs plural), which catches duplicates that exact-slug lookup misses. Existing pages are updated conservatively.
 
 New stubs use the templates in `_lumina/schema/page-templates.md`.
 
@@ -172,10 +197,14 @@ node _lumina/scripts/wiki.mjs add-citation sources/<slug> sources/<cited-slug>
 
 Do not create stubs for cited sources not yet ingested — note them in `## Open Questions`.
 
+Write checkpoint: `phase: "citations"`.
+
 ### Phase 7 — Update wiki/index.md
 
 Add the new source page (and any new concept/person pages) to the catalog between `<!-- lumina:index -->` markers. Format: `- [[sources/<slug>]] — <one-line description>`.
 
+Write checkpoint: `phase: "index"`.
+
 ## Draft Gate
 
 Present a draft summary to the user:
@@ -196,7 +225,7 @@ Use the user's configured communication language. Explain "provenance", "edges",
   ```
   → NEXT
 - **E**: Take the user's revision instructions. Re-edit the affected files (source page, stubs, or edges as instructed). Re-present the draft summary. Loop back to "HALT and ask human" — do not advance.
-- **Q**: Leave the phase-level checkpoint in place; do not write `ingest_status`. **STOP — do not read the NEXT directive below.** Exit cleanly with no further action this run. The next `/lumi-ingest <slug>` invocation resumes from this point.
+- **Q**: Leave the phase-level checkpoint in place; do not write `ingest_status`. Before exiting, tell the user in plain language that the draft pages and links written so far stay in the wiki as work-in-progress — coming back to `/lumi-ingest <slug>` continues from here, and `/lumi-reset` can clean up if they decide not to keep this source at all. **STOP — do not read the NEXT directive below.** Exit cleanly with no further action this run.
 
 ## NEXT
 

package/src/skills/core/ingest/references/step-03-verify.md

@@ -3,7 +3,7 @@
 ## RULES
 
 - Read `README.md` at the project root before this step if you have not already in this session.
-- Reuse the existing `/lumi-verify` skill in grounding-only mode. Do not inline a duplicate grounding reviewer here — single source of truth for grounding logic lives in `src/skills/core/verify/`.
+- Reuse the existing `/lumi-verify` skill in grounding-only mode. Do not inline a duplicate grounding reviewer here — single source of truth for grounding logic lives in `.agents/skills/lumi-verify/`.
 - All frontmatter writes go through `wiki.mjs set-meta`. Never write to `wiki/*.md` directly.
 - Drift is a hard halt: a missing `raw_paths` file is a stronger signal than any finding and should not be silently downgraded.
 - This step asks the user only when there are source-check findings, missing source files, or a confidence downgrade. If the source check passes, continue automatically.
@@ -24,7 +24,7 @@ Invoke `/lumi-verify` on the entry restricted to the grounding reviewer. Three r
 
 **Tier 1 — Agent tool available (Claude Code):**
 
-Spawn a sub-agent with the verify SKILL prompt and the slug, instructing it to run grounding only (skip blind, skip external). Wait for completion, then read the writeback:
+Spawn a sub-agent instructed to read and follow `.agents/skills/lumi-verify/SKILL.md` with this slug as the target, grounding only (skip blind, skip external). The sub-agent is deliberate: it activates the verify skill in a blank context, so the verdict is not anchored by the reasoning chain that just drafted the pages. Do not invoke the verify skill inline in this conversation (e.g. via a skill-invocation tool) — same-context verification inherits drafting bias. Wait for completion, then read the writeback:
 
 ```bash
 node _lumina/scripts/wiki.mjs read-meta sources/<slug>
@@ -32,9 +32,9 @@ node _lumina/scripts/wiki.mjs read-meta sources/<slug>
 
 **Tier 2 — Bash-only runtime (Codex, Gemini, Cursor, generic):**
 
-Read fully and follow `src/skills/core/verify/SKILL.md` Grounding pipeline (Section: "Grounding reviewer"), with this slug as the target. The verify skill's writeback contract is the same — `verify_status` and `findings` written to the entry frontmatter. After the grounding pass returns, control returns to this step's Phase 8.6.
+Read fully and follow `.agents/skills/lumi-verify/SKILL.md` Grounding pipeline (Section: "Grounding reviewer"), with this slug as the target. The verify skill's writeback contract is the same — `verify_status` and `findings` written to the entry frontmatter. After the grounding pass returns, control returns to this step's Phase 8.6.
 
-If `src/skills/core/verify/references/reviewers.md` exists, it is the canonical Grounding reviewer prompt; load it as part of following the verify SKILL.
+If `.agents/skills/lumi-verify/references/reviewers.md` exists, it is the canonical Grounding reviewer prompt; load it as part of following the verify SKILL.
 
 **Tier 3 — User opts out:**
 
@@ -54,6 +54,7 @@ Inspect `verify_status` and `findings`:
 | `findings_pending` | Patch/defer findings written | Present findings inline; user chooses A/E/W/Q |
 | `drift_detected` | `raw_paths` resolves to missing files | **Hard HALT** — do not present standard menu; force user to repair raw or set `provenance: missing` explicitly |
 | `skipped` | Tier 3 opt-out | Write verified status and continue automatically; the user already opted out |
+| `not_applicable` | Verify refused: target is not a `sources/*` entry | Should never happen during ingest (the target is always `sources/<slug>`). Treat as an internal error: HALT, report the slug that was passed to verify, and do not advance `ingest_status`. |
 
 For `passed`, tell the user in one short sentence that the page matched the source closely enough to continue. Then write `ingest_status: verified` and go to NEXT:
 

package/src/skills/core/ingest/references/step-04-finalize.md

@@ -4,7 +4,7 @@
 
 - All frontmatter writes go through `wiki.mjs set-meta`.
 - `wiki/log.md` is append-only. Use `wiki.mjs log` — never edit the file directly.
-- The phase-level checkpoint at `_lumina/_state/ingest-<slug>.json` ends here; mark it `phase: "done"`.
+- The phase-level checkpoint at `_lumina/_state/ingest-<file-basename>.json` ends here; mark it `phase: "done"`.
 
 ## Why this step exists
 

package/src/skills/core/init/SKILL.md

@@ -69,6 +69,11 @@ For reading pack (if installed):
 node _lumina/scripts/wiki.mjs init --pack reading
 ```
 
+For learning pack (if installed):
+```bash
+node _lumina/scripts/wiki.mjs init --pack learning
+```
+
 Each call returns `{ ok: true, created: [...], skipped: [...] }`. Report which
 directories were newly created and which already existed.
 
@@ -168,6 +173,8 @@ node _lumina/scripts/lint.mjs --json
 node _lumina/scripts/wiki.mjs log init "Wiki initialized. Packs: core, research. Created: 8 dirs."
 ```
 Additional dirs created: `wiki/foundations/`, `wiki/topics/`, `raw/discovered/`
+(research pack). The learning pack (`init --pack learning`) additionally
+creates `wiki/reflections/`.
 </example>
 
 <example>

package/src/skills/core/migrate-legacy/SKILL.md

@@ -178,11 +178,22 @@ Use the following inference order. Stop at the first tier that yields a result.
 
 **Tier 1 (authoritative): read the ingest checkpoint.**
 
+Ingest checkpoints are keyed by the source file's basename
+(`_lumina/_state/ingest-<file-basename>.json`), not by slug — there is no
+direct `<slug>` lookup. List every ingest checkpoint and match by content:
+
 ```bash
-node _lumina/scripts/wiki.mjs checkpoint-read ingest <slug>
+ls _lumina/_state/ingest-*.json 2>/dev/null
 ```
 
-If a checkpoint exists with a `source_path` field:
+Read each match with the Read tool and check its `slug` field. Newer ingests
+(post-checkpoint-slug-merge) store `"slug": "sources/<slug>"` directly in the
+checkpoint — match the checkpoint whose `slug` equals the entry being
+migrated. Older checkpoints predate this field and won't have it; if no
+checkpoint's `slug` matches (including the case where none carry the field at
+all), fall through to Tier 2.
+
+If a matching checkpoint is found and has a `source_path` field:
 - If `source_path` is under `raw/tmp/*`: do NOT write `raw_paths`. Tell the user:
   "`<slug>` was ingested from a transient location (`<source_path>`). Move the
   file to `raw/sources/` or `raw/download/<resource>/` and re-run
@@ -308,13 +319,14 @@ URL=$(node _lumina/scripts/wiki.mjs read-meta sources/<slug> | node -e "process.
 
 # Step 2 — write urls array
 node _lumina/scripts/wiki.mjs set-meta sources/<slug> urls "[\"$URL\"]" --json-value
-
-# Step 3 — remove legacy url key (set-meta with empty string removes the key)
-node _lumina/scripts/wiki.mjs set-meta sources/<slug> url --remove
 ```
 
-If `set-meta --remove` is not supported by the installed wiki.mjs version, use `Edit` to
-remove the `url:` line directly after confirming `urls:` was written successfully.
+`set-meta` cannot remove a frontmatter key today — there is no `--remove`
+flag. After confirming `urls:` was written successfully, remove the legacy
+`url:` line with the `Edit` tool directly. This is the one sanctioned
+exception to "never hand-edit wiki frontmatter" in this skill, and it is
+limited strictly to deleting the obsolete `url:` key — do not use `Edit` for
+any other frontmatter change.
 
 After backfilling all entries, proceed immediately to Phase 4.
 
@@ -402,7 +414,7 @@ Report to the user:
 2. Entries updated — count and slugs grouped by field.
 3. Inferred values — the inference table from Phase 2 (so the user can review).
 4. Lint result after backfill — must show 0 errors.
-5. Whether `legacyMigrationNeeded` was cleared in the manifest.
+5. Whether the upgrade cleanup is finished.
 
 ## Examples
 
@@ -464,7 +476,10 @@ Re-running this skill on a clean wiki produces zero file changes.
 - Never modify files in `raw/`. Read-only.
 - Never hand-edit `wiki/graph/edges.jsonl` or `wiki/graph/citations.jsonl`.
 - `set-meta` is the only permitted write path for frontmatter changes in this
-  skill. Do not use Edit or Write on wiki pages directly.
+  skill, with one sanctioned exception: deleting the obsolete `url:` key
+  during the `url` → `urls` schema-shape upgrade (Phase 3), since `set-meta`
+  has no key-removal flag. Do not use Edit or Write on wiki pages for
+  anything else.
 - Do not clear `legacyMigrationNeeded` until lint confirms 0 errors.
 - If the CHANGELOG has no `### Migration` section for the detected version gap,
   rely entirely on the L01/L11 finding messages to identify which fields need

package/src/skills/core/reset/SKILL.md

@@ -47,12 +47,14 @@ Key workspace paths:
 |-------|----------------|-------------|
 | `wiki` | All files under `wiki/` (keeps directory structure) | Only from git |
 | `raw` | All files under `raw/sources/`, `raw/notes/`, `raw/assets/` | Not from wiki |
-| `state` | `_lumina/_state/*.json` checkpoint files | Yes — re-ingest regenerates |
-| `checkpoints` | `_lumina/_state/ingest-*.json` only | Yes — re-ingest regenerates |
+| `state` | Everything under `_lumina/_state/`, including subfolders (saved reviewer prompts, feed state) | Yes — re-ingest regenerates |
+| `checkpoints` | Every `<skill>-<phase>.json` file directly under `_lumina/_state/` — this is ANY checkpoint, not just ingest: resume points, research-discover shortlists, discovery-phase checkpoints, and saved `/lumi-verify` report files (`lumi-verify-<ts>.json`) | Yes for ingest/discover checkpoints — re-run regenerates. **No** for saved `/lumi-verify` reports — those are deleted too and are not regenerated automatically. |
 | `all` | `wiki` + `state` — leaves `raw/` untouched | Only wiki from git |
 
-The `checkpoints` scope is the safest reset — it only clears in-progress ingest
-state. Use it when an ingest got stuck and you want a clean restart.
+The `checkpoints` scope is the lowest-risk reset in terms of what it targets
+(no wiki content), but it is not scoped to "ingest only" — warn the user that
+any saved `/lumi-verify` reports under `_lumina/_state/` are removed along with
+stuck ingest checkpoints.
 
 ## Instructions
 
@@ -73,18 +75,37 @@ node _lumina/scripts/reset.mjs --scope <scope> --dry-run
 ```
 
 The `--dry-run` flag makes `reset.mjs` print the deletion plan without deleting
-anything and does not require `--yes`. Example output:
+anything and does not require `--yes`. `reset.mjs` reports aggregate
+per-directory counts, not a per-file list. Example output:
 
 ```
-[DRY RUN] Scope: wiki
-  Would delete: wiki/sources/lora.md
-  Would delete: wiki/concepts/lora-adapter.md
-  Would delete: wiki/log.md
-  ...
-  Total: 23 files
+Plan: --scope wiki --yes
+Would delete:
+  wiki/  (23 files, 45.2 KB)
+Would recreate:
+  wiki/index.md  (empty)
+  wiki/log.md  (empty)
+Total: 23 files, 45.2 KB
 ```
 
-Present this list to the user verbatim.
+For the `checkpoints` scope, the deleted directory is labeled to make clear
+only checkpoint files count toward the total, e.g.:
+
+```
+Plan: --scope checkpoints --yes
+Would delete:
+  _lumina/_state/ (checkpoints only)  (3 files, 1.8 KB)
+Total: 3 files, 1.8 KB
+```
+
+Present the real aggregate plan to the user, and also translate it into one
+plain sentence so a non-technical reader gets the point immediately, e.g.
+"This will permanently delete 23 files under wiki/ — about 45 KB."
+
+If the plan's final line reads `Total: 0 files, 0 B`, there is nothing to
+delete. Skip Step 3 (confirmation) entirely — report "Nothing to delete for
+scope `<scope>`; already clean." and stop. Do not ask for a "yes" that has
+nothing to confirm.
 
 ### Step 3 — Require explicit confirmation
 
@@ -139,13 +160,15 @@ re-verify directory structure).
 
 **Before execution:**
 ```
-Reset plan for scope: <scope>
-Files to delete:
-  wiki/sources/lora.md
-  wiki/concepts/lora-adapter.md
-  (N more...)
-Total: <N> files
-
+Plan: --scope <scope> --yes
+Would delete:
+  wiki/  (23 files, 45.2 KB)
+Would recreate:
+  wiki/index.md  (empty)
+  wiki/log.md  (empty)
+Total: 23 files, 45.2 KB
+
+This will permanently delete 23 files under wiki/ — about 45 KB.
 Type yes to confirm, anything else to cancel.
 ```
 
@@ -161,16 +184,25 @@ Next: run /lumi-init to re-seed the wiki, then /lumi-ingest to rebuild content.
 <example>
 User: "The ingest for attention-revisited got killed. Start it over."
 
-Safest reset — clear a single stuck checkpoint:
+Safest reset — clear a single stuck checkpoint. `--scope checkpoints` deletes
+every checkpoint file under `_lumina/_state/`, not just this one — check the
+count before confirming:
 ```bash
 node _lumina/scripts/reset.mjs --scope checkpoints --dry-run
-# shows: Would delete: _lumina/_state/ingest-attention-revisited-2026.json
+# shows:
+#   Plan: --scope checkpoints --yes
+#   Would delete:
+#     _lumina/_state/ (checkpoints only)  (1 files, 0.4 KB)
+#   Total: 1 files, 0.4 KB
+# Only one checkpoint exists right now, so this is safe.
 # User confirms: yes
 node _lumina/scripts/reset.mjs --scope checkpoints --yes
 node _lumina/scripts/wiki.mjs log reset "Scope: checkpoints. 1 file deleted."
 ```
 Suggest: "Now run `/lumi-ingest raw/sources/attention-revisited.pdf` to restart."
-Checkpoint scope is the lowest-risk reset — only in-progress state is removed.
+Checkpoint scope is lower-risk than `wiki` or `raw` (no wiki content touched),
+but if other checkpoints exist (other stuck ingests, saved `/lumi-verify`
+reports) they are deleted too — the dry-run count is the only way to know.
 </example>
 
 <example>
@@ -189,9 +221,10 @@ After reset, log.md is gone — recreate it with the reset entry, then suggest
 User: "Reset everything." (then reconsiders after seeing the plan)
 
 Escalation / reconsideration — user sees the dry-run plan for `all` scope:
-Show the deletion tree for wiki/ and state only. Explicitly state: "`all` does
-not delete raw/; use `--scope raw` only when you intend to remove user-owned
-sources." User replies "cancel". Report: "Reset cancelled. No files were deleted."
+Show the aggregate deletion plan for `wiki/` and `_lumina/_state/` only.
+Explicitly state: "`all` does not delete raw/; use `--scope raw` only when you
+intend to remove user-owned sources." User replies "cancel". Report: "Reset
+cancelled. No files were deleted."
 Never execute without the
 literal word "yes" — ambiguous confirmations like "ok" or "sure" do not count.
 </example>

package/src/skills/core/verify/SKILL.md

@@ -61,6 +61,7 @@ Accepted invocations:
 - `/lumi-verify --all` — verify every `sources/*` entry
 - `/lumi-verify --since <date>` — verify entries whose `updated` >= `<date>` (ISO 8601 date or datetime). Reject malformed dates with exit 1.
 - `/lumi-verify --external` — additionally run the External reviewer (open-web check). Default is offline-only (Blind + Grounding).
+- `/lumi-verify --stage <...>` — run the reviewers and report findings but do not write anything to the page (see Step 5); useful for a preview pass.
 
 Resolve the target list:
 

package/src/skills/packs/learning/reflect/SKILL.md

@@ -150,7 +150,7 @@ or update the reflection page:
 Append a log entry via the wiki engine:
 
 ```bash
-node _lumina/scripts/wiki.mjs log lumi-learning-reflect "reflected on <concept-id>; evolution_count=<N>"
+node _lumina/scripts/wiki.mjs log learning-reflect "reflected on <concept-id>; evolution_count=<N>"
 ```
 
 Then report to the user:

package/src/skills/packs/reading/chapter-ingest/SKILL.md

@@ -76,10 +76,10 @@ re-running against the same chapter slug produces byte-identical output.
    graph files by hand.
 8. Append one line through the wiki engine:
    ```bash
-   node _lumina/scripts/wiki.mjs log chapter-ingest "<book-slug> ch<N> \"<chapter-title>\" -> <K> characters, <M> themes"
+   node _lumina/scripts/wiki.mjs log reading-chapter-ingest "<book-slug> ch<N> \"<chapter-title>\" -> <K> characters, <M> themes"
    ```
    Log entry text:
-   `## [YYYY-MM-DD] chapter-ingest | <book-slug> ch<N> "<chapter-title>" → <K> characters, <M> themes`
+   `## [YYYY-MM-DD] reading-chapter-ingest | <book-slug> ch<N> "<chapter-title>" → <K> characters, <M> themes`
 9. Self-verification: run `node _lumina/scripts/wiki.mjs read-edges chapters/<book-slug>/<chapter-slug> --json`
    and confirm that at least one `features` edge and one `tagged_with` edge are present.
    If either is missing, add the missing edges before finishing.

package/src/skills/packs/reading/character-track/SKILL.md

@@ -117,7 +117,7 @@ slug. The engine is idempotent: re-adding a correctly formed edge is a safe no-o
 Update `wiki/index.md` if new character pages were created, append the activity via:
 
 ```bash
-node _lumina/scripts/wiki.mjs log character-track "<book-slug> ch<N> -> <K> characters updated, <M> edges added"
+node _lumina/scripts/wiki.mjs log reading-character-track "<book-slug> ch<N> -> <K> characters updated, <M> edges added"
 ```
 
 Run `node _lumina/scripts/lint.mjs --json` when available; use `--fix` only for
@@ -133,7 +133,7 @@ index/frontmatter fixes within this skill's scope.
 - All inter-character edges use namespaced slugs.
 - `wiki/index.md` updated when character pages were created.
 - `wiki/log.md` has a new entry:
-  `## [YYYY-MM-DD] character-track | <book-slug> ch<N> → <K> characters updated, <M> edges added`
+  `## [YYYY-MM-DD] reading-character-track | <book-slug> ch<N> → <K> characters updated, <M> edges added`
 - Lint/check run where available; unresolved issues are reported with exact slugs.
 
 ## Guardrails

package/src/skills/packs/reading/theme-map/SKILL.md

@@ -126,7 +126,7 @@ one, it was promoted prematurely — revert to stub status and note in the repor
 Then update `wiki/index.md` if new theme pages were created, append the activity via:
 
 ```bash
-node _lumina/scripts/wiki.mjs log theme-map "<book-slug> -> <K> themes promoted, <M> stubs pending"
+node _lumina/scripts/wiki.mjs log reading-theme-map "<book-slug> -> <K> themes promoted, <M> stubs pending"
 ```
 
 Run `node _lumina/scripts/lint.mjs --json` when available; use `--fix` only for
@@ -140,7 +140,7 @@ index/frontmatter fixes within this skill's scope.
 - Theme stubs for single-chapter tags remain as stubs (not promoted).
 - `wiki/index.md` updated when pages were created or promoted.
 - `wiki/log.md` has a new entry:
-  `## [YYYY-MM-DD] theme-map | <book-slug> → <K> themes promoted, <M> stubs pending`
+  `## [YYYY-MM-DD] reading-theme-map | <book-slug> → <K> themes promoted, <M> stubs pending`
 - Lint/check run where available; unresolved issues are reported with exact slugs.
 
 ## Guardrails

package/src/skills/packs/research/prefill/SKILL.md

@@ -113,7 +113,7 @@ python3 _lumina/tools/fetch_wikipedia.py page "<title>"
 6. Log the addition:
 
 ```bash
-node _lumina/scripts/wiki.mjs log lumi-research-prefill "prefilled foundation <slug>"
+node _lumina/scripts/wiki.mjs log research-prefill "prefilled foundation <slug>"
 ```
 
 7. Run lint with fix so `wiki/index.md` and structural checks stay current:
@@ -122,6 +122,10 @@ node _lumina/scripts/wiki.mjs log lumi-research-prefill "prefilled foundation <s
 node _lumina/scripts/lint.mjs --fix --json
 ```
 
+8. Suggest `/lumi-check` in a fresh session or via a subagent after this run.
+   A blank context catches bias from the reasoning chain that just wrote the
+   foundation page.
+
 ## Constraints
 
 - Do not create concept pages from this skill; use `/lumi-ingest` for wiki
@@ -140,6 +144,6 @@ node _lumina/scripts/lint.mjs --fix --json
 - Foundation page exists with valid frontmatter and concise source-backed body.
 - `node _lumina/scripts/lint.mjs --fix --json` has updated `wiki/index.md` if
   needed and leaves `summary.errors === 0`.
-- `wiki/log.md` has an append-only `lumi-research-prefill` entry.
+- `wiki/log.md` has an append-only `research-prefill` entry.
 - If the page already existed, the user's choice (skip / refresh / abort) is logged
   in `wiki/log.md` with the actual decision taken.

package/src/skills/packs/research/rank/SKILL.md

@@ -150,7 +150,7 @@ References:
 8. **Log the activity.**
 
    ```bash
-   node _lumina/scripts/wiki.mjs log lumi-research-rank "ranked <slug>: infl=<n>, 4C=<c/c/c/c>"
+   node _lumina/scripts/wiki.mjs log research-rank "ranked <slug>: infl=<n>, 4C=<c/c/c/c>"
    ```
 
 9. **Report to the user in plain language.** Summarize what you found — how

package/src/skills/packs/research/survey/SKILL.md

@@ -18,8 +18,23 @@ not discover or ingest new sources here; gaps should be reported explicitly.
 
 ## Context
 
-Read `README.md` first. Use `_lumina/scripts/wiki.mjs` for entity and graph
-queries:
+Read `README.md` first. Survey pages live under `wiki/summary/` and use the
+same frontmatter contract as any other summary page: `id`, `title`,
+`type: summary`, `created`, `updated`, and `covers` (an array of every wiki
+page slug the survey draws on). `covers` is required — a summary page without
+it fails lint (L01).
+
+When speaking with the user, follow the README language rule exactly. Use the
+configured communication language and avoid technical tool words unless the
+user asks for them.
+
+## Instructions
+
+1. Identify the topic scope and the source/concept pages that support it. Ask
+   the user a clarifying question if the scope is ambiguous rather than
+   guessing.
+
+2. Read only relevant wiki pages and graph edges:
 
 ```bash
 node _lumina/scripts/wiki.mjs list-entities --type sources
@@ -28,36 +43,131 @@ node _lumina/scripts/wiki.mjs read-meta sources/<slug>
 node _lumina/scripts/wiki.mjs read-edges sources/<slug>
 ```
 
-## Instructions
+3. Synthesize the survey in chat. Cite every claim to a wiki page
+   (`[[sources/<slug>]]` or `[[concepts/<slug>]]`) and add an explicit gaps
+   section naming what the wiki does not yet cover or where sources disagree.
+   This is a draft — do not write any file yet.
+
+4. Ask the user whether to save the survey. Do not write
+   `wiki/summary/<slug>.md` until the user explicitly asks to save it. If the
+   user only wanted an answer in chat, stop here.
+
+5. If the user asks to save, generate the slug:
+
+```bash
+node _lumina/scripts/wiki.mjs slug "<survey title>"
+```
+
+6. Check whether `wiki/summary/<slug>.md` already exists:
+
+```bash
+node _lumina/scripts/wiki.mjs read-meta summary/<slug>
+```
 
-1. Identify the topic scope and the source/concept pages that support it.
-2. Read only relevant wiki pages and graph edges.
-3. Synthesize the survey with cited source references and a section for gaps or
-   unresolved disagreements.
-4. If the user asks to save it, write `wiki/summary/<survey-slug>.md` with valid
-   summary frontmatter and link the covered pages.
-5. Log the saved survey:
+   - **exit 2 (not found)** — continue to step 7.
+   - **exit 0 (exists)** — read the file, then show the user the `title` and
+     `created` date. Ask exactly one question with three options in the user's
+     language (no other action until answered). Explain the choices plainly:
+
+     ```
+     Survey "<title>" already exists.
+       [s] skip    — abort, no changes (default)
+       [r] refresh — replace the survey body with the new draft; preserve `created` and `<!-- user-edited -->` sections
+       [a] abort   — same as skip but log the user's intent
+     ```
+
+     Map blank/Enter to `skip`. Do not proceed without an explicit choice.
+
+7. Write `wiki/summary/<slug>.md` with valid summary frontmatter and the two
+   standard sections. Use today's date for both `created` and `updated` on a
+   new page; on a refresh keep the original `created` date. `covers` must list
+   every wiki page slug the survey cites — omitting it is the most common way
+   this skill fails lint.
+
+   ```markdown
+   ---
+   id: <slug>
+   title: "<Survey Title>"
+   type: summary
+   created: YYYY-MM-DD
+   updated: YYYY-MM-DD
+   covers:
+     - sources/<slug>
+     - concepts/<slug>
+     - ...
+   ---
+
+   ## Survey
+
+   <!-- The narrative synthesis, written in document_output_language, with
+        inline [[wikilinks]] to every cited page. -->
+
+   ## Gaps
+
+   <!-- Bullet list of what the wiki does not yet cover, or where sources
+        disagree. Keep the section even when empty — write "none identified"
+        rather than omitting it. -->
+   ```
+
+8. Log the saved survey:
 
 ```bash
-node _lumina/scripts/wiki.mjs log lumi-research-survey "saved survey <survey-slug>"
+node _lumina/scripts/wiki.mjs log research-survey "saved survey <slug>"
 ```
 
-6. When a survey page is saved, run lint with fix so `wiki/index.md` and graph
-   checks stay current:
+   On a refresh, write `"refreshed survey <slug> ..."` instead.
+
+9. Run lint with fix so `wiki/index.md` and structural checks stay current:
 
 ```bash
 node _lumina/scripts/lint.mjs --fix --json
 ```
 
+   If `summary.errors > 0`, read the lint output, address each error, and
+   re-run before telling the user the skill is done.
+
+10. Suggest `/lumi-check` in a fresh session or via a subagent after saving. A
+    blank context catches bias from the reasoning chain that just wrote the
+    survey.
+
 ## Constraints
 
 - Do not read raw source files unless the user explicitly asks for a gap audit.
 - Do not create new source or concept pages.
 - Do not claim coverage beyond the current wiki graph.
+- Do not write `wiki/summary/<slug>.md` before the user explicitly asks to
+  save the survey — an unsaved survey lives only in the chat response.
+- When refreshing an existing survey, preserve the original `created` date and
+  any `<!-- user-edited -->` sections verbatim. Only `updated`, the survey
+  body, and `covers` may change.
+
+## Examples
+
+<example>
+User asks: "What does the wiki know about attention mechanisms?" without
+asking to save it.
+Action: read the `sources` and `concepts` entity lists, read edges for the
+relevant pages, then answer in chat with citations to `[[sources/...]]` and
+`[[concepts/...]]`, plus a gaps note (for example: "no source yet covers
+sparse attention variants"). No slug is generated and no file is written.
+</example>
+
+<example>
+User asks the same question, then says "save that as a survey".
+Action: generate the slug, confirm `wiki/summary/attention-mechanisms.md`
+does not already exist, write the page with a `covers` array listing every
+cited source and concept slug plus the `## Survey` / `## Gaps` sections, log
+`research-survey "saved survey attention-mechanisms"`, run
+`lint.mjs --fix --json`, and suggest running `/lumi-check` in a fresh session.
+</example>
 
 ## Definition of Done
 
 - Unsaved survey responses name supporting wiki pages and explicit gaps.
-- Saved survey pages have valid summary frontmatter and cite covered pages.
+- Saved survey pages have valid summary frontmatter, including a non-empty
+  `covers` array listing every cited page.
+- The survey file was written only after the user explicitly asked to save it.
 - If saved, lint leaves `summary.errors === 0`, `wiki/index.md` is current, and
-  `wiki/log.md` has an append-only `lumi-research-survey` entry.
+  `wiki/log.md` has an append-only `research-survey` entry.
+- If the page already existed, the user's choice (skip / refresh / abort) is
+  logged in `wiki/log.md` with the actual decision taken.

package/src/skills/packs/research/topic/SKILL.md

@@ -66,14 +66,17 @@ node _lumina/scripts/wiki.mjs list-entities --type sources
 node _lumina/scripts/wiki.mjs list-entities --type concepts
 ```
 
-   If the user named a seed concept, also fetch its immediate neighbours:
+   If the user named a seed concept that already exists as a concept page, also
+   fetch its immediate neighbours (the topic title itself is never a seed slug —
+   the topic page does not exist yet, so do not run read-edges against it):
 
 ```bash
 node _lumina/scripts/wiki.mjs read-edges concepts/<seed-slug>
 ```
 
    From the combined output, select 5-10 candidate sources and 5-10 candidate
-   concepts most relevant to the topic. Present them as a numbered list with a
+   concepts most relevant to the topic. On a small wiki with fewer than 5 of
+   either, propose all relevant ones — a shorter list is fine. Present them as a numbered list with a
    one-line reason for each. Group sources and concepts separately. Explain that
    the user can:
    - confirm the list as shown,
@@ -124,29 +127,24 @@ node _lumina/scripts/wiki.mjs read-edges concepts/<seed-slug>
         Leave blank if none are obvious; the user can fill this in later. -->
    ```
 
-5. Write bidirectional edges for every approved source and concept. For each
-   approved source, add both directions:
+5. Write edges for every approved source and concept. Call `add-edge` once for
+   the forward relationship from the topic page — the engine writes the
+   reverse edge automatically. For each approved source:
 
 ```bash
 node _lumina/scripts/wiki.mjs add-edge topics/<slug> includes_source sources/<source-slug>
-node _lumina/scripts/wiki.mjs add-edge sources/<source-slug> included_in_topic topics/<slug>
 ```
 
-   For each approved concept, add both directions:
+   For each approved concept:
 
 ```bash
 node _lumina/scripts/wiki.mjs add-edge topics/<slug> covers_concept concepts/<concept-slug>
-node _lumina/scripts/wiki.mjs add-edge concepts/<concept-slug> covered_by_topic topics/<slug>
 ```
 
-   If `add-edge` is not the correct subcommand, check available subcommands with
-   `node _lumina/scripts/wiki.mjs --help` and use the correct one before
-   proceeding.
-
 6. Log the operation:
 
 ```bash
-node _lumina/scripts/wiki.mjs log lumi-research-topic "created topic <slug> covering <N> sources, <M> concepts"
+node _lumina/scripts/wiki.mjs log research-topic "created topic <slug> covering <N> sources, <M> concepts"
 ```
 
    On a refresh, write `"refreshed topic <slug> ..."` instead.
@@ -160,15 +158,19 @@ node _lumina/scripts/lint.mjs --fix --json
    If `summary.errors > 0`, read the lint output, address each error, and re-run
    before telling the user the skill is done.
 
+8. Suggest `/lumi-check` in a fresh session or via a subagent after this run. A
+   blank context catches bias from the reasoning chain that just built the
+   topic page.
+
 ## Constraints
 
 - Do not read `raw/` files at any point. All information comes from already-ingested
   wiki pages and graph edges.
 - Do not create concept or source pages from this skill. If a candidate the user
   wants does not have a wiki page, tell them to run `/lumi-ingest` first.
-- Every forward link from the topic page to a concept or source must have a
-  reverse edge written in the same operation. This is a hard graph rule — do not
-  skip it.
+- Every forward link from the topic page to a concept or source needs a
+  reverse edge — the engine writes the reverse edge in the same operation.
+  Never add reverse edges manually.
 - When refreshing an existing topic, preserve the original `created` date and any
   `<!-- user-edited -->` sections verbatim. Only `updated`, `key_sources`, and
   non-marked sections may change.
@@ -183,9 +185,10 @@ node _lumina/scripts/lint.mjs --fix --json
   entry) and all four standard sections (Description / Key sources / Key
   concepts / Open questions).
 - Bidirectional edges exist for every linked source and concept — forward from
-  the topic page and reverse on each source and concept page.
+  the topic page, written once via `add-edge`, with the reverse edge on each
+  source and concept page written automatically by the engine.
 - `node _lumina/scripts/lint.mjs --fix --json` leaves `summary.errors === 0`.
-- `wiki/log.md` has an append-only `lumi-research-topic` entry recording the
+- `wiki/log.md` has an append-only `research-topic` entry recording the
   slug, source count, and concept count.
 - If the page already existed, the user's choice (skip / refresh / abort) is
   logged in `wiki/log.md` with the actual decision taken.

package/src/skills/packs/research/watch-run/SKILL.md

@@ -30,11 +30,14 @@ with the research pack and depends on:
 - `_lumina/tools/fetch_rss.py` — used by the runner for `type: feed` items.
 
 The runner is **manual** — Lumina does not poll feeds in the background. The
-user (or their scheduler) decides when to trigger this skill. See
-`docs/user-guide/advanced-scheduled-discovery.{en,vi,zh}.md` for cron /
-launchd / Task Scheduler templates (trilingual), and
-`docs/user-guide/research-watch.md` for the v1.4 feed schema, etag /
-XXE / per-feed-state deep-dive (English).
+user (or their scheduler) decides when to trigger this skill. See the online
+guide at
+https://github.com/tronghieu/lumina-wiki/blob/main/docs/user-guide/advanced-scheduled-discovery.en.md
+(also in Vietnamese at .../advanced-scheduled-discovery.vi.md and Simplified
+Chinese at .../advanced-scheduled-discovery.zh.md) for cron / launchd / Task
+Scheduler templates, and the online guide at
+https://github.com/tronghieu/lumina-wiki/blob/main/docs/user-guide/research-watch.md
+for the v1.4 feed schema, etag / XXE / per-feed-state deep-dive (English).
 
 ## Instructions
 
@@ -79,12 +82,16 @@ Never dump raw JSON or stack traces to the user — keep it conversational.
 
 ### 4. If the user asks about scheduling
 
-Point them at `docs/user-guide/advanced-scheduled-discovery.{en,vi,zh}.md`
-(trilingual cron / launchd / Task Scheduler patterns) and the included
-wrapper `_lumina/scripts/scheduler-samples/cron-daily.sh`. For v1.4 feed
-schema / etag / XXE specifics, the deep-dive lives at
-`docs/user-guide/research-watch.md` (English). Do not edit their crontab
-or launchd files; explain the snippets and let them paste.
+Point them at the online guide (trilingual cron / launchd / Task Scheduler
+patterns) at
+https://github.com/tronghieu/lumina-wiki/blob/main/docs/user-guide/advanced-scheduled-discovery.en.md
+(.vi.md and .zh.md for Vietnamese and Simplified Chinese) and the included
+wrapper `_lumina/scripts/scheduler-samples/cron-daily.sh` — that file is a
+local path, shipped with the workspace. For v1.4 feed schema / etag / XXE
+specifics, the deep-dive lives at the online guide
+https://github.com/tronghieu/lumina-wiki/blob/main/docs/user-guide/research-watch.md
+(English). Do not edit their crontab or launchd files; explain the snippets
+and let them paste.
 
 ## Constraints
 

package/src/skills/packs/research/watchlist/SKILL.md

@@ -160,14 +160,17 @@ Tell the user:
 - papers are downloaded later during `/lumi-ingest`, after the user chooses a
   candidate.
 
-If the user asks how to schedule it, point them to
-`docs/user-guide/advanced-scheduled-discovery.{en,vi,zh}.md` (trilingual
-cron / launchd / Actions / Task Scheduler patterns) and the
-`/lumi-research-watch-run` skill which runs one pass over the watchlist on
-demand. They can also follow an RSS / Atom feed by adding a `type: feed`
-item (https URL required) — the advanced-scheduled-discovery guide §7 has
-the YAML example, and `docs/user-guide/research-watch.md` carries the v1.4
-technical deep-dive (English).
+If the user asks how to schedule it, point them to the online guide at
+https://github.com/tronghieu/lumina-wiki/blob/main/docs/user-guide/advanced-scheduled-discovery.en.md
+(also available in Vietnamese at
+.../advanced-scheduled-discovery.vi.md and Simplified Chinese at
+.../advanced-scheduled-discovery.zh.md — trilingual cron / launchd / Actions /
+Task Scheduler patterns) and the `/lumi-research-watch-run` skill which runs
+one pass over the watchlist on demand. They can also follow an RSS / Atom feed
+by adding a `type: feed` item (https URL required) — the advanced-scheduled-
+discovery guide §7 has the YAML example, and the online guide at
+https://github.com/tronghieu/lumina-wiki/blob/main/docs/user-guide/research-watch.md
+carries the v1.4 technical deep-dive (English).
 
 ## Constraints
 

package/src/templates/README.md

@@ -129,6 +129,7 @@ When you write a forward link, **always write the reverse link in the same opera
 | `concepts/K` writes `[[source-E]]`          | `sources/E` appends K to `Related concepts`|
 | `summary/S` writes `[[concept-K]]`          | `concepts/K` appends S to `Mentioned in`   |
 {{#if pack_research}}| `topics/T` writes `[[concept-K]]`           | `concepts/K` appends T to `Topics`         |
+| `topics/T` writes `[[source-A]]`            | `sources/A` appends T to `Topics`          |
 {{/if}}{{#if pack_reading}}| `chapters/Ch` writes `[[character-X]]`      | `characters/X` appends Ch to `Key chapters`|
 | `chapters/Ch` writes `[[theme-Y]]`          | `themes/Y` appends Ch to `Traced in`       |
 {{/if}}

package/src/templates/README.vi.md

@@ -129,6 +129,7 @@ Khi bạn viết một liên kết chiều đi, **luôn viết liên kết ngư
 | `concepts/K` viết `[[source-E]]`                | `sources/E` thêm K vào `Related concepts`         |
 | `summary/S` viết `[[concept-K]]`                | `concepts/K` thêm S vào `Mentioned in`            |
 {{#if pack_research}}| `topics/T` viết `[[concept-K]]`                 | `concepts/K` thêm T vào `Topics`                  |
+| `topics/T` viết `[[source-A]]`                  | `sources/A` thêm T vào `Topics`                   |
 {{/if}}{{#if pack_reading}}| `chapters/Ch` viết `[[character-X]]`            | `characters/X` thêm Ch vào `Key chapters`         |
 | `chapters/Ch` viết `[[theme-Y]]`                | `themes/Y` thêm Ch vào `Traced in`                |
 {{/if}}

package/src/templates/README.zh.md

@@ -130,6 +130,7 @@
 | `concepts/K` 写 `[[source-E]]`              | `sources/E` 将 K 追加到 `Related concepts`  |
 | `summary/S` 写 `[[concept-K]]`              | `concepts/K` 将 S 追加到 `Mentioned in`     |
 {{#if pack_research}}| `topics/T` 写 `[[concept-K]]`               | `concepts/K` 将 T 追加到 `Topics`           |
+| `topics/T` 写 `[[source-A]]`                | `sources/A` 将 T 追加到 `Topics`            |
 {{/if}}{{#if pack_reading}}| `chapters/Ch` 写 `[[character-X]]`          | `characters/X` 将 Ch 追加到 `Key chapters`  |
 | `chapters/Ch` 写 `[[theme-Y]]`              | `themes/Y` 将 Ch 追加到 `Traced in`         |
 {{/if}}