[green-dalii]

Split out of #755. The code is @weqoocu's; the split, and the one removal described below, are mine. The commit carries their author line.

Two free-text fields that shape what the model looks for and writes about, without touching any contract the plugin owns:

• extractionFocus — appended to the extraction prompt's Extraction Scope block as a domain-priority hint. It narrows what the model looks for; it does not replace the JSON protocol, the classification rules or the tag vocabulary.
• contentRequirements — appended to entity/concept page generation through a {{content_requirements}} placeholder after the merge-strategy block. It controls emphasis and structure; citation, wikilink, merge and anti-hallucination rules stay binding.

Empty is the default, and empty adds nothing, so every vault that never configures these gets byte-identical prompts and keeps its prefix cache. Both fields are capped at 4,000 characters, so a runaway paste cannot bloat every batch.

What I removed, and the evidence

The submitted change also carried a per-topic override layer: settings.wikiTopics, activeTopicId, a WikiTopic interface, and a resolution path that preferred a topic's own fields over the global ones.

It could not run. Nothing in the settings UI creates or edits a wikiTopics entry, and nothing elsewhere writes the field, so it was always []. activeTopicId had no reader and no writer. The only trace in the UI was a description string naming a scope the user could not reach.

The key difference from "unused API surface": the submitted code was activeTopic(settings, ...).find(...) — a branch that every prompt build evaluated and that could never be true. Shipping it means every future reader has to prove unreachability again before trusting the feature. The repository's rule for this is wire it or delete it before a release.

This is a deletion of your work, @weqoocu, and it is reversible by adding the picker that writes the field. I have recorded it as an issue rather than dropping it silently; if you want the layer here instead, say so and the third PR goes up as-is with the picker alongside it.

i18n

Eight new keys in all eleven locales, key sets identical so the type barrel stays honest. Japanese, Korean, German, French, Spanish, Portuguese, Italian and Russian currently carry the English text; Chinese and Traditional Chinese are translated. That gap is real — it is called out here rather than left for a user to discover, and translating it is a separate, reviewable change.

Gate 4: Performance

Dim	Status	Notes
CPU	✅	Two trim + length checks per prompt build. The clamp allocates only when the field exceeds 4,000 chars
Memory	✅	Two strings on the settings object; no cache, no map
IO	✅	No change
Network	✅	No change
Token	⚠️	This is the point of the feature, so it is worth naming: a configured focus or requirements block adds its own text to every extraction and every page generation. The 4,000-char cap bounds it, and the default (empty) adds zero. A user who fills both fields close to the cap adds roughly 1,500-3,000 tokens per call — that is their choice, and it is visible in the settings panel

Credit, stated rather than assumed

If this merges by squash, the merge commit's author becomes the PR author — me — and @weqoocu's contribution would read as mine. A rebase merge keeps their author line. That decision belongs to the maintainer at merge time, not to me.

Gate 1: lint 0, tsc 0, build clean, 369 test files / 5,047 tests, css-lint 0.

[green-dalii]

Follow-up: the i18n gap I flagged in the PR body is now closed.

56 strings — 7 keys × 8 locales — for Japanese, Korean, German, French, Spanish, Portuguese, Italian and Russian. Chinese and Traditional Chinese were already translated.

The wording follows each locale's existing terms rather than a fresh glossary. The extraction section is 抽出 in ja, 추출 in ko, Extraktion in de, Extraction in fr, Extracción in es, Extração in pt, Estrazione in it, Извлечение in ru — the terms each file already uses for its own extraction settings. The placeholder examples keep the English source's shape (main characters, game modes, weapons, battle pass) so the reader sees a concrete domain instead of a transliteration.

Two things this does not do

The lintTagViolation* cluster is still untranslated in the same eight locales. It predates this feature — Retagging {current}/{total}, Retag failed for {path}, Retag complete…, 🏷️ Retag {count} page(s) with LLM and two others, 6 keys × 8 locales = 48 strings. I am not bundling them here: a fix that carries an unrelated gap cannot be reviewed on its own terms. It needs its own PR.

No guard test is added in this PR. The parity test checks that every key exists in every locale. It cannot see that a key holds the English text — which is exactly how the 56 strings above shipped with the feature and passed every check. A guard is worth adding, but the threshold has to be chosen against measurement rather than guessed: a blanket "must differ from English" rule would flag the ~5 % of strings that are legitimately identical across locales (language names, API Key, AWS SSO, format templates). The measured candidate is "English description strings of ≥40 characters", which currently flags exactly the two lintTagViolation keys and nothing else — clean once those are translated.

Gate 1: lint 0, tsc 0, build clean, 369 test files / 5,047 tests, css-lint 0.

[KvikullSigurdur]

I ran this branch at 56ebcd8 with one extra test, and found two places where contentRequirements does not reach the written page, plus one design question about page types. Sharing in case it is useful before merge.

The test uses the setting's own placeholder as the requirement (contentRequirementsPlaceholder, en.ts:414, without the "e.g."): Cite the source episode/chapter when known; use "reportedly/inferred" for unsourced lore; keep a Risk Notes section where applicable.

It drives createOrUpdateEntityPage with a fake model client that records every prompt and returns a page with a ## Risk Notes section.

Check	Result
The creation prompt carries the requirement	✓
The written page keeps the ## Risk Notes section the model wrote	✗
A merge into an existing page carries the requirement	✗

1. A requested section is removed after generation

create-page.ts:245 runs stripUnknownSections against the built-in section labels. Any heading outside that list is dropped, so ## Risk Notes is gone from the written page while Description, Related Entities, Related Concepts and Mentions in Source stay. merge-page.ts:353 and related-page.ts:174 apply the same filter.

So the placeholder's own example cannot take effect. The setting's description also lists "structure" among the things it controls (contentRequirementsDesc, en.ts:413, and prompt-focus.ts:71).

2. Merges run without the requirement

{{content_requirements}} is in generateEntityPage and generateConceptPage only (generation.ts:19, :79), and create-page.ts:210 is the only call that fills it. A merge into an existing page sends two prompts, the merge triage and mergeEntityPage, and neither carries the requirement. So the setting shapes a page when it is created, and every later source that touches the page is written without it.

import { describe, it, expect } from 'vitest';
import { createOrUpdateEntityPage, type CreatePageContext } from '../../../wiki/page-factory/create-page';
import { createMockEntity } from '../../__support__/factories';
import type { LLMWikiSettings, WikiPageRef } from '../../../types';
import { mockExistingWikiPages } from '../../__support__/engine-context';
// The settings placeholder from src/texts/en.ts, without its "e.g." prefix.

const REQUIREMENT = 'Cite the source episode/chapter when known; use "reportedly/inferred" for unsourced lore; keep a Risk Notes section where applicable';

const MODEL_REPLY = '---\ntype: entity\ntags: [person]\naliases: ["Ada"]\n---\n\n# Ada Lovelace\n\n## Description\nMathematician.\n\n## Risk Notes\n- Some attributions are reportedly disputed.\n\n## Related Entities\n- [[Charles Babbage]]';

const EXISTING_PAGE = '---\ntype: entity\ncreated: 2026-07-10\nupdated: 2026-07-10\nsources:\n  - "[[older-note]]"\ntags: [person]\n---\n\n# Ada Lovelace\n\n## Description\nOlder body.\n';
function makeCtx(files: Record<string, string> = {}) {

const store = new Map(Object.entries(files));

const prompts: string[] = [];

const ctx = {

app: { vault: { getMarkdownFiles: () => [], read: async (f: { path: string }) => store.get(f.path) ?? '' } },

settings: { wikiFolder: 'wiki', wikiLanguage: 'en', slugCase: 'preserve', disableThinking: false, contentRequirements: REQUIREMENT } as LLMWikiSettings,

async tryReadFile(p: string) { return store.get(p) ?? null; },

async createOrUpdateFile(p: string, c: string) { store.set(p, c); },

getClient: () => ({ createMessage: async (args: { messages: Array<{ content: unknown }> }) => {

prompts.push(args.messages.map(m => String(m.content)).join('\n'));

return MODEL_REPLY;

} }),

buildSystemPrompt: async () => 'system',

getExistingWikiPages(): Promise<WikiPageRef[]> { return mockExistingWikiPages(this)(); },

} as unknown as CreatePageContext;

return { ctx, store, prompts };

}
const SOURCE = { path: 'notes/ada.md', basename: 'ada.md' };
describe('#895 contentRequirements', () => {

it('the creation prompt carries the requirement', async () => {

const { ctx, prompts } = makeCtx();

await createOrUpdateEntityPage(ctx, createMockEntity({ name: 'Ada Lovelace' }), undefined, SOURCE);

expect(prompts.some(p => p.includes(REQUIREMENT))).toBe(true);           // passes

});
it('the written page keeps the Risk Notes section the model wrote', async () => {

const { ctx, store } = makeCtx();

const r = await createOrUpdateEntityPage(ctx, createMockEntity({ name: 'Ada Lovelace' }), undefined, SOURCE);

expect(store.get(r.path!)).toContain('## Description');                  // passes

expect(store.get(r.path!)).toContain('## Risk Notes');                   // fails

});
it('a merge carries the requirement', async () => {

const { ctx, prompts } = makeCtx({ 'wiki/entities/Ada-Lovelace.md': EXISTING_PAGE });

const r = await createOrUpdateEntityPage(ctx, createMockEntity({ name: 'Ada Lovelace' }), undefined, SOURCE);

expect(r.created).toBe(false);                                           // passes: this is a merge

expect(prompts.map(p => p.includes(REQUIREMENT))).toEqual([true, true]); // fails: [false, false]

});

});

[green-dalii]

@KvikullSigurdur — both findings reproduce here. I ran them independently rather than taking the report as read, and they are correct.

Reproduction (my own file, src/__tests__/wiki/page-factory/content-requirements-effect.test.ts, same shape as yours):

× FINDING 1: the written page keeps the Risk Notes section the model wrote
  AssertionError: expected '---\ntype: entity\ncreated: 2026-10-2…' to contain '## Risk Notes'
× FINDING 2: a merge carries the requirement
  AssertionError: expected [ false, false ] to deeply equal [ true, true ]

Mechanism, confirmed at the source:

• stripUnknownSections(content, Object.values(labels)) — create-page.ts:240, merge-page.ts:353, related-page.ts:174. It drops any ## heading whose canonical label is not in SECTION_LABELS[wikiLanguage]. The section list is plugin-owned and language-scoped.
• {{content_requirements}} appears in generation.ts:19 and :79 only. create-page.ts:210 is the only place that fills it. The merge path renders mergeAnalysis / mergeEntityPage / mergeConceptPage / appendToReviewedPage / updateRelatedPage and passes no such key, so renderTemplate never sees it.

Neither defect came from the split. The original branch had the same shape: generation.ts carried the placeholder twice and merge.ts carried it zero times — merge.ts was never touched by the commit that introduced the feature. My split moved code; it did not create this.

The review gap was mine. The 14 tests in #895 assert that the template CONTAINS {{content_requirements}} and that the rendered output does not contain the literal placeholder. Both pass while the feature does nothing to a written page. That is the placeholder-contract test standing in for an effect test — the same shape this project keeps hitting, and I did not catch it on review. The effect test above is the one that should have existed.

The two findings are different in kind

Finding 2 is a wiring gap and should be fixed. The setting shapes a page at creation and is silently absent on every later write. A page built from five sources has the requirement in the first and not in the other four — a page that is inconsistent with itself, which is worse than the setting not existing.

Finding 1 is a promise that the mechanism cannot keep, and that is a design decision, not a bug to patch.

The section list is plugin-owned. mergeEntityPage even enforces it explicitly (- ## {{section_description}}: …), and mergeAnalysis reads the same labels. So a page cannot gain a section from a prompt, and the project's own schema rule says the schema owns page structure while the plugin injects runtime parameters. Letting a prompt invent a section would break that separation, and it would also break the merge path, which must know the label set to strip and re-assert headings.

So there are two coherent answers, and this needs a decision rather than a patch:

• A. Narrow the promise. contentRequirements controls emphasis and content within the known sections; it does not add sections. Then the description and the placeholder example change, and the setting still delivers something real — the merge wiring is fixed, and the model is told to weight, emphasise and cover aspects inside ## Description, ## Related Entities and the rest.
• B. Let the user declare sections. The setting gains a way to name extra sections, and they join the allowed label set for the write. That is a schema-layer change: the section list stops being language-scoped and fixed, which touches stripUnknownSections, canonicalizeSectionHeaders, the merge triage prompt and the related-sections logic. It is a bigger change than this PR, and it deserves its own issue and its own measurement.

I lean towards A for this PR, with B recorded as a separate piece of work — but @weqoocu wrote the feature and the call is theirs.

One question the report opens but does not write out: you mentioned "one design question about page types". It is not in the body, so I do not have it. If it is the A-versus-B question above, I have stated it. If it is something else — how a custom section interacts with the per-type label set, say — please write it out, because that is the part I would otherwise guess at.

What is not blocking the release

contentRequirements does not exist on main — zero hits in types.ts, no prompt-focus.ts. It ships in this PR, which is scheduled for v1.30.0 MINOR. Nothing here affects 1.29.0.

Where this leaves the PR

Two of the three assertions in the original body are still mine to fix, and I will not merge this with the placeholder test as the only evidence:

1. The merge path carries the requirement — I will add {{content_requirements}} to the merge prompts and to appendToReviewedPage / updateRelatedPage, and fill it at the merge call sites.
2. The effect test exists, so a placeholder-only test can no longer be mistaken for a working feature.

The section-list question is @weqoocu's to answer, and the description text depends on it. I am holding the merge until that is settled, because the honest options produce different descriptions and I would rather write one final text than two.

The reproduction test is on my branch, not this one, so this PR's CI stays green while the decision is open. Say the word and I push it here as the RED that drives the fix.

[KvikullSigurdur]

Sorry about the misleading page types question, it is something I had in mind but then edited out forgetting I had foreshadowed it. I started going over issues because I like the plugin a lot but would like a more granular control of the structure (sections) created for each note.

I am not quite caught up enough on the architecture to weigh in on #873, but the idea came up that if this PR meant to introduce the feature of letting users define sections, it might be nice to control sections per page type. Events pages could have a timeline section, projects could have risks etc.

[green-dalii]

@KvikullSigurdur
Thanks for the correction, and for going through the issues — that is useful in its own right, not a distraction.

Your two findings reproduce here independently, and they are now pinned in the branch. content-requirements-effect.test.ts drives the page factory with a recording fake client and reads the file on disk, instead of checking that a prompt template contains a placeholder. Both are committed as expected failures rather than left red, so the suite stays green and each one flips the moment it is fixed — which is how we will know the marker has to come off.

I recorded the whole thing, your per-page-type idea included, in #902. The short version of why it is an issue and not a patch in this PR:

• A merge carrying the requirement is a wiring gap. It gets fixed.
• A user-named section surviving the write is a different thing: the section list is plugin-owned on purpose, so it is a decision about what the setting may promise, not a defect to patch quietly.
• Section control per page type — timeline on events, risks on projects — is that decision plus a further step, because the allowed set becomes a function of the page type rather than one global list. It also overlaps Let a user define their own page-type taxonomy and folder layout, through the injection layer rather than the schema file #873 (page-type taxonomy) and Feature: Add explicit event marker/type and enhanced local indices for improved LLM-Wiki structuring #112 (event type), and it has to arrive through the settings injection layer rather than the schema file, since a settings-driven value baked into the schema reintroduces the two-sources problem the project spent a release removing.

So your request is written down where it will actually be acted on.

Please keep sending reports like this one. The reproduction and the file:line references made it cheap to confirm, and any other friction you run into is worth a note — issues and PR threads are both fine.