trustwiki 0.1.0-alpha.0

package/cli/rules/index.js

@@ -0,0 +1,19 @@
+import { rule as frontmatterRequired } from './frontmatter-required.js';
+import { rule as frontmatterFields } from './frontmatter-fields.js';
+import { rule as placeholderPresent } from './placeholder-present.js';
+import { rule as linkBroken } from './link-broken.js';
+import { rule as indexMissing } from './link-index-missing.js';
+import { rule as typeMismatch } from './link-type-mismatch.js';
+import { rule as pageOrphan } from './page-orphan.js';
+import { rule as citationMalformed } from './citation-malformed.js';
+import { rule as citationTarget } from './citation-target-missing.js';
+import { rule as excessInferred } from './provenance-excess-inferred.js';
+import { rule as lowConfidence } from './provenance-low-confidence.js';
+import { rule as contradicted } from './provenance-contradicted.js';
+
+export const RULES = [
+  frontmatterRequired, frontmatterFields, placeholderPresent,
+  linkBroken, indexMissing, typeMismatch, pageOrphan,
+  citationMalformed, citationTarget,
+  excessInferred, lowConfidence, contradicted,
+];

package/cli/rules/link-broken.js

@@ -0,0 +1,22 @@
+function resolvesTo(model, pageTarget) {
+  const norm = pageTarget.replace(/\.md$/, '');
+  if (model.filePaths.has(`${norm}.md`)) return true;
+  const base = `${norm.split('/').pop()}.md`;
+  const hits = [...model.filePaths].filter(p => p.endsWith(`/${base}`) || p === base);
+  return hits.length === 1;
+}
+
+export const rule = {
+  id: 'link.broken',
+  run(model) {
+    const out = [];
+    for (const f of model.files) for (const l of f.links) {
+      const pageTarget = l.target.split('#')[0]; // [[page#Section]] → page
+      if (!pageTarget) continue; // pure-anchor link: nothing to resolve here
+      if (!resolvesTo(model, pageTarget)) out.push({ file: f.relPath, line: l.line,
+        message: `broken wikilink [[${l.target}]]`,
+        hint: 'fix the path or create the target page' });
+    }
+    return out;
+  },
+};

package/cli/rules/link-index-missing.js

@@ -0,0 +1,30 @@
+function listedEntryResolves(model, norm) {
+  if (model.filePaths.has(`${norm}.md`)) return true;
+  const base = `${norm.split('/').pop()}.md`;
+  const hits = [...model.filePaths].filter(p => p.endsWith(`/${base}`) || p === base);
+  return hits.length === 1;
+}
+
+export const rule = {
+  id: 'link.index-missing', needs: 'index',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      const norm = f.relPath.replace(/\.md$/, '');
+      let listed = model.indexEntries.has(norm);
+      if (!listed) {
+        const base = norm.split('/').pop();
+        listed = [...model.indexEntries].some(e => e.endsWith(`/${base}`) || e === base);
+      }
+      if (!listed) out.push({ file: f.relPath, line: 1,
+        message: 'missing from index',
+        hint: `add an entry to ${model.config.index}` });
+    }
+    for (const [norm, line] of model.indexLines) {
+      if (!listedEntryResolves(model, norm)) out.push({ file: model.config.index, line,
+        message: `index entry does not resolve: [[${norm}]]`,
+        hint: 'fix the path or remove the entry' });
+    }
+    return out;
+  },
+};

package/cli/rules/link-type-mismatch.js

@@ -0,0 +1,16 @@
+export const rule = {
+  id: 'link.type-mismatch',
+  run(model) {
+    const out = [];
+    if (!Object.keys(model.config.typeByDir).length) return out; // no-op by design
+    for (const f of model.files) {
+      const topDir = f.relPath.split('/')[0];
+      const want = model.config.typeByDir[topDir];
+      const got = f.fm.ok ? f.fm.fields.type : undefined;
+      if (want && got && got !== want) out.push({ file: f.relPath, line: 1,
+        message: `type "${got}" does not match directory type "${want}"`,
+        hint: `set type: ${want} or move the page` });
+    }
+    return out;
+  },
+};

package/cli/rules/page-orphan.js

@@ -0,0 +1,14 @@
+export const rule = {
+  id: 'page.orphan',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      if (!f.fm.ok) continue;
+      const n = f.links.length;
+      if (n < model.config.minOutboundLinks) out.push({ file: f.relPath, line: 1,
+        message: `only ${n} outbound link(s) — orphaned page`,
+        hint: `weave in at least ${model.config.minOutboundLinks} related pages` });
+    }
+    return out;
+  },
+};

package/cli/rules/placeholder-present.js

@@ -0,0 +1,17 @@
+const RE = /\b(TODO|TBD|FIXME|lorem ipsum)\b/i;
+
+export const rule = {
+  id: 'placeholder.present',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      const head = f.body.split('\n').slice(0, 20).join('\n');
+      const m = head.match(RE);
+      if (m) out.push({ file: f.relPath,
+        line: f.bodyStartLine + head.slice(0, m.index).split('\n').length - 1,
+        message: `placeholder text: ${m[0]}`,
+        hint: 'unfinished content erodes trust — finish or remove' });
+    }
+    return out;
+  },
+};

package/cli/rules/provenance-contradicted.js

@@ -0,0 +1,31 @@
+const CALLOUT = /\[!contradiction\]([^\n]*)/;
+
+export const rule = {
+  id: 'provenance.contradicted',
+  run(model) {
+    const out = [];
+    const targetsIn = b => [...b.matchAll(/\[\[([^\]|\n]+)/g)].map(x => x[1].trim().replace(/\.md$/, ''));
+    for (const f of model.files) {
+      const m = f.body.match(CALLOUT);
+      const calloutTargets = m ? targetsIn(m[1]) : [];
+      const fmList = (f.fm?.fields?.contradicted_by || '').replace(/[\[\]]/g, '');
+      const fmTargets = fmList ? fmList.split(',').map(s => s.trim()).filter(Boolean).map(t => t.replace(/\.md$/, '')) : [];
+      if (m && !fmTargets.length) out.push({ file: f.relPath,
+        line: f.bodyStartLine + f.body.slice(0, m.index).split('\n').length - 1,
+        message: 'contradiction callout without contradicted_by in frontmatter',
+        hint: 'mirror the contradiction in frontmatter so lint can check both sides' });
+      if (!m && fmTargets.length) out.push({ file: f.relPath, line: 1,
+        message: 'contradicted_by lists targets but no [!contradiction] callout in body',
+        hint: 'surface the conflict in the body so readers see it' });
+      if (m && fmTargets.length) {
+        const a = new Set(calloutTargets), b = new Set(fmTargets);
+        const onlyCallout = [...a].filter(t => !b.has(t));
+        const onlyFm = [...b].filter(t => !a.has(t));
+        if (onlyCallout.length || onlyFm.length) out.push({ file: f.relPath, line: 1,
+          message: `contradiction target sets differ — callout-only: [${onlyCallout.join(', ') || 'none'}], frontmatter-only: [${onlyFm.join(', ') || 'none'}]`,
+          hint: 'make the body callout and contradicted_by list agree' });
+      }
+    }
+    return out;
+  },
+};

package/cli/rules/provenance-excess-inferred.js

@@ -0,0 +1,21 @@
+export const rule = {
+  id: 'provenance.excess-inferred',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      if (!f.fm.ok) continue;
+      if (model.config.inferredSkipTypes.includes(f.fm.fields.type)) continue;
+      const prose = f.paragraphs.filter(p => p.isProse && p.text);
+      if (!prose.length) continue;
+      // a paragraph counts as cited only when a citation sits on its final line
+      const citedLines = new Set(f.citations.map(c => c.line));
+      const uncited = prose.filter(p => !citedLines.has(p.startLine + p.text.split('\n').length - 1));
+      if (uncited.length / prose.length > model.config.inferredThreshold) {
+        out.push({ file: f.relPath, line: uncited[0].startLine,
+          message: `${uncited.length}/${prose.length} prose paragraphs uncited (>${model.config.inferredThreshold})`,
+          hint: 'cite sources at paragraph end, or mark the page as inference — unattributed claims erode trust' });
+      }
+    }
+    return out;
+  },
+};

package/cli/rules/provenance-low-confidence.js

@@ -0,0 +1,15 @@
+export const rule = {
+  id: 'provenance.low-confidence',
+  run(model) {
+    const out = [];
+    for (const f of model.files) {
+      const c = Number(f.fm?.ok ? f.fm.fields.confidence : NaN);
+      if (!Number.isNaN(c) && c < model.config.confidenceFloor) {
+        out.push({ file: f.relPath, line: 1,
+          message: `confidence ${c} below floor ${model.config.confidenceFloor}`,
+          hint: 'add sources to raise confidence, or archive the page' });
+      }
+    }
+    return out;
+  },
+};

package/cli/walk.js

@@ -0,0 +1,19 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const SKIP = new Set(['.git', 'node_modules']);
+
+export async function walkVault(root, roots, indexFile = null) {
+  const out = [];
+  async function rec(rel) {
+    const abs = join(root, rel);
+    for (const entry of await readdir(abs, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || SKIP.has(entry.name)) continue;
+      const relChild = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) await rec(relChild);
+      else if (entry.name.endsWith('.md') && relChild !== indexFile) out.push(relChild);
+    }
+  }
+  for (const r of roots.length ? roots : ['.']) await rec(r === '.' ? '' : r);
+  return out.sort();
+}

package/docs/method.md

@@ -0,0 +1,69 @@
+# The trustwiki method — one rule, twelve checks
+
+The one rule: **never write a claim your vault cannot trace.** Agent-written
+knowledge bases fail in predictable ways; each rule below exists because its
+failure mode was observed, repeatedly, in production. Grouped by what they
+protect.
+
+## Truth
+
+### citation.malformed
+A citation that doesn't parse is decoration, not provenance. The check
+validates every `^[…]` against the grammar in `schema/spec.md` (path, optional
+`:42-58` or `#L42-L58` range, comma-separated multi-source).
+*Incident class:* hand-written citations that "look right" but were never
+resolvable — the visual signature of provenance without the substance.
+
+### citation.target-missing
+Every cited path must exist in the vault. A citation pointing at a file that
+isn't there is a lie with a hair cut.
+*Incident class:* pages renamed or archived without sweeping their backlinks.
+
+### provenance.excess-inferred
+Inference is legitimate; invisible inference is not. When more than the
+threshold (default 30%) of a page's prose paragraphs carry no citation, the
+page is flagged. Source pages (`type: source`) are exempt — they quote, they
+don't cite themselves.
+*Incident class:* the slop-vault — fluent, confident prose that no source
+can confirm. This is the failure mode people mean when they say "AI slop".
+
+### provenance.low-confidence
+Pages may declare `confidence: 0–1`. Below the floor (default 0.5) the page
+is flagged so weak claims are visible at a glance.
+
+## Conflict
+
+### provenance.contradicted
+When two pages disagree, the disagreement is data. The rule enforces the
+two halves: a `> [!contradiction]` callout in the body **and** a
+`contradicted_by` list in frontmatter — either half alone is flagged,
+because machines read frontmatter and humans read prose.
+*Incident class:* a contradiction quietly rewritten away, then rediscovered
+six weeks later by someone re-deriving the same wrong conclusion.
+
+## Structure
+
+### link.broken
+Every `[[wikilink]]` must resolve — by exact path or unique basename.
+### link.index-missing
+Every page must appear in the index; every index entry must resolve.
+*Incident class:* index corruption — entries glued onto one line by a bad
+edit, silently dropping every second page from navigation.
+### link.type-mismatch
+If you declare expected `type` per directory, pages must match it.
+### page.orphan
+Fewer than `minOutboundLinks` (default 2) outbound links → flagged. Islands
+rot first.
+### frontmatter.required / frontmatter.fields
+No frontmatter, or missing required fields (`title, created, updated, type,
+tags`; sources add `source_url, ingested, sha256`) — flagged. The sha256 is
+how a silently edited source is caught months later.
+### placeholder.present
+`TODO`/`TBD`/`FIXME` in the first twenty body lines. Unfinished content that
+looks finished erodes trust in everything around it.
+
+## The operating loop
+
+Ingest → Synthesize → Evolve → Gate. See `SKILL.md` for the agent-facing
+method; see `schema/spec.md` for the frozen grammar. Chinese version:
+`docs/method.zh.md`.

package/docs/method.zh.md

@@ -0,0 +1,61 @@
+# trustwiki 方法——一条铁律，十二道检查
+
+铁律：**永远不要写下知识库无法溯源的论断。** agent 维护的知识库以一种
+可预测的方式腐烂；下面每条规则都来自生产环境中反复出现的真实事故。
+按保护对象分组。
+
+## 真相
+
+### citation.malformed
+解析不了的引用只是装饰，不是溯源。检查器按 `schema/spec.zh.md` 的文法
+校验每个 `^[…]`（路径、可选 `:42-58` / `#L42-L58` 区间、逗号分隔多来源）。
+*事故类型*：看起来像引用、实际永远无法解析的手写引用——有溯源的外形，
+没有溯源的实体。
+
+### citation.target-missing
+被引用的路径必须存在于库内。指向不存在文件的引用是剪了头发的谎言。
+*事故类型*：页面改名或归档时没有清扫反向引用。
+
+### provenance.excess-inferred
+推断是合法的；不可见的推断不是。当一页未引用散文段落占比超过阈值
+（默认 30%）时标记。来源页（`type: source`）豁免——它们引用来源，
+不需要引用自己。
+*事故类型*：slop 库——流畅、自信、没有任何来源能佐证的散文。
+这就是人们说"AI slop"时指的那种失败。
+
+### provenance.low-confidence
+页面可声明 `confidence: 0–1`。低于下限（默认 0.5）即标记，
+让弱论断一眼可见。
+
+## 冲突
+
+### provenance.contradicted
+两页相左时，分歧本身就是数据。规则强制两半齐备：正文
+`> [!contradiction]` callout **加** frontmatter `contradicted_by` 列表——
+只有一半就标记，因为机器读 frontmatter 而人读正文。
+*事故类型*：矛盾被悄悄改写抹平，六周后有人重新推导出同一个错误结论。
+
+## 结构
+
+### link.broken
+每个 `[[wikilink]]` 必须可解析——精确路径或全局唯一 basename。
+### link.index-missing
+每页必须进索引；每个索引项必须可解析。
+*事故类型*：索引腐化——一次坏编辑把两行条目粘成一行，导航里静默消失
+一半的页面。
+### link.type-mismatch
+声明了目录级期望 `type` 后，页面必须匹配。
+### page.orphan
+出链少于 `minOutboundLinks`（默认 2）即标记。孤岛先腐烂。
+### frontmatter.required / frontmatter.fields
+缺 frontmatter 或缺必填字段（`title, created, updated, type, tags`；
+来源页另需 `source_url, ingested, sha256`）即标记。sha256 是数月后
+发现来源被静默篡改的唯一手段。
+### placeholder.present
+正文前二十行里的 `TODO`/`TBD`/`FIXME`。看起来完成的未完成内容，
+会侵蚀周围一切的信任。
+
+## 运行循环
+
+Ingest → Synthesize → Evolve → Gate。面向 agent 的方法见 `SKILL.md`；
+冻结文法见 `schema/spec.md`。English version: `docs/method.md`.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "trustwiki",
+  "version": "0.1.0-alpha.0",
+  "description": "Provenance linter and method for agent-maintained knowledge bases — every claim cited, contradictions surfaced, rot detected.",
+  "type": "module",
+  "bin": {
+    "trustwiki": "cli/bin.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "cli",
+    "schema",
+    "templates",
+    "SKILL.md",
+    "README.md",
+    "README.zh.md",
+    "docs/method.md",
+    "docs/method.zh.md",
+    "proof"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/QianJinGuo/trustwiki.git"
+  }
+}

package/proof/STATS.md

@@ -0,0 +1,18 @@
+# Living stats — the proof vault
+
+trustwiki is not a thought experiment: the method runs in production on an
+agent-maintained personal knowledge base. Every number below carries its
+source and verification date — the same discipline this tool enforces.
+
+| metric | value | source | verified |
+|---|---|---|---|
+| operating since | 2026-05 | oldest rotation archive `log-2026-05.md` | 2026-09-05 |
+| tracked pages | 8,658 | `scripts/wiki-lint.mjs` (the authoritative counter this linter was generalized from) | 2026-09-05 |
+| raw source pages | 4,162 | file count under `raw/articles/` | 2026-09-05 |
+| lint errors | 0 | same wiki-lint run (92 warnings, exit 0) | 2026-09-05 |
+| provenance warnings surfaced by trustwiki | 15,052 | stricter defaults (inference ratio, orphans) on the same vault — see `scripts/parity-check.mjs` | 2026-09-05 |
+| automated jobs | ingest + quality pipelines on cron; daily public projection | CRON.md | 2026-09-05 |
+
+The gap between "0 errors" and "15,052 warnings" is the point: the production
+vault is clean by its own rules, and trustwiki's stricter defaults still find
+rot worth looking at. Diagnosis is a dial, not a verdict.

package/schema/spec.md

@@ -0,0 +1,110 @@
+# trustwiki-schema v0.1
+
+## Status
+
+`trustwiki-schema v0.1` — frozen 2026-09-05. Additions only, never rewrites,
+until v0.2. This schema is implemented by the `trustwiki` linter and the
+`trustwiki` agent skill; other tools MAY implement it.
+
+## Citation grammar
+
+```
+citation    := "^[" source-list "]"
+source-list := source ( ", " source )*
+source      := path ( line-ref | anchor-ref )?
+path        := vault-relative path; the .md suffix is optional
+line-ref    := ":" start "-" end        e.g. ^[sources/abc.md:42-58]
+anchor-ref  := "#L" start "-L" end      e.g. ^[sources/abc.md#L42-L58]
+start, end  := positive integers; start ≤ end
+```
+
+Worked examples:
+
+```markdown
+Tea brews differently by style.^[sources/tea.md]
+
+Steeping times dominate the bitterness outcome.^[sources/tea.md:42-58]
+
+Both studies agree on the ratio.^[sources/study-a.md, sources/study-b.md#L3-L4]
+```
+
+Placement rules:
+
+- Citations attach to the end of prose paragraphs. Never to headings, list
+  items, code blocks, or callouts.
+- Uncited inference is allowed — knowledge synthesis requires it — but the
+  share of uncited prose paragraphs on a page must stay under the configured
+  threshold (default 0.3), and honest pages mark inference as inference via
+  frontmatter (`provenance_state: inferred`).
+- Raw source pages (`type: source`) are exempt from the inference ratio:
+  they quote the source, they do not cite themselves.
+
+## Frontmatter
+
+Required on every page:
+
+| field    | type   | notes                          |
+|----------|--------|--------------------------------|
+| title    | string | human-readable page title      |
+| created  | date   | ISO date, set once             |
+| updated  | date   | ISO date, bumped on every edit |
+| type     | string | page type (e.g. note, source, moc) |
+| tags     | list   | `[a, b]`                       |
+
+Additional required on source pages (`type: source` or pages under the
+configured `sourceDir`):
+
+| field      | type   | notes                                   |
+|------------|--------|-----------------------------------------|
+| source_url | string | original URL                             |
+| ingested   | date   | when the source was captured             |
+| sha256     | string | hash of the raw body at capture time — this is how silent source edits are detected later |
+
+Optional provenance fields:
+
+| field            | type   | notes                                            |
+|------------------|--------|--------------------------------------------------|
+| confidence       | float  | 0–1; below the floor (default 0.5) is flagged    |
+| provenance_state | enum   | `extracted \| merged \| inferred \| ambiguous`   |
+| contradicted_by  | list   | slugs of pages that disagree with this one       |
+
+## Contradiction marking
+
+When two pages disagree, the disagreement is surfaced, not resolved away:
+
+1. Body callout at the end of the disagreeing page:
+   `> [!contradiction] see [[other-page]] which holds the opposite view`
+2. Frontmatter mirror: `contradicted_by: [other-page]`
+
+The linter's `provenance.contradicted` rule requires both halves — a callout
+without the frontmatter mirror (or vice versa) is flagged, because
+machines read one and humans read the other.
+
+## Checking your vault
+
+```bash
+npx trustwiki lint ./your-vault
+```
+
+Configuration lives in `.trustwiki.json` at the vault root (all keys optional):
+
+| key                 | default   | meaning                                     |
+|---------------------|-----------|---------------------------------------------|
+| roots               | `["."]`   | directories that participate in scanning    |
+| index               | `null`    | index file; enables index-drift rules       |
+| sourceDir           | `null`    | root for citation path resolution           |
+| typeByDir           | `{}`      | expected `type` per top-level directory     |
+| minOutboundLinks    | `2`       | orphan threshold                            |
+| inferredThreshold   | `0.3`     | max share of uncited prose paragraphs       |
+| confidenceFloor     | `0.5`     | minimum confidence                          |
+| inferredSkipTypes   | `["source"]` | page types exempt from inference ratio   |
+| rules               | all on    | per-rule `error \| warn \| off`             |
+
+Rule ids: `frontmatter.required`, `frontmatter.fields`, `placeholder.present`,
+`link.broken`, `link.index-missing`, `link.type-mismatch`, `page.orphan`,
+`citation.malformed`, `citation.target-missing`,
+`provenance.excess-inferred`, `provenance.low-confidence`,
+`provenance.contradicted`.
+
+Exit codes: `0` clean (warnings allowed), `1` at least one error,
+`2` configuration or usage error.

package/schema/spec.zh.md

@@ -0,0 +1,103 @@
+# trustwiki-schema v0.1（中文版）
+
+## 状态
+
+`trustwiki-schema v0.1`——2026-09-05 冻结。v0.2 之前只增不改。本规范由
+`trustwiki` linter 与同名 agent skill 实现，其他工具亦可实现。
+
+## 引用语法
+
+```
+citation    := "^[" source-list "]"
+source-list := source ( ", " source )*
+source      := path ( line-ref | anchor-ref )?
+path        := vault 内相对路径；.md 后缀可省略
+line-ref    := ":" start "-" end        例：^[sources/abc.md:42-58]
+anchor-ref  := "#L" start "-L" end      例：^[sources/abc.md#L42-L58]
+start, end  := 正整数；start ≤ end
+```
+
+示例：
+
+```markdown
+不同茶类冲泡方式不同。^[sources/tea.md]
+
+浸泡时间是苦涩的主导因素。^[sources/tea.md:42-58]
+
+两项研究对比率结论一致。^[sources/study-a.md, sources/study-b.md#L3-L4]
+```
+
+放置规则：
+
+- 引用挂在散文段落末尾；不得挂在标题、列表项、代码块或 callout 上。
+- 允许无引用的推断——知识合成离不开推断——但单页未引用散文段落占比
+  不得超过阈值（默认 0.3），且诚实页面用 frontmatter 标注推断
+  （`provenance_state: inferred`）。
+- 原始来源页（`type: source`）豁免推断占比：它们引用来源本身，
+  不需要引用自己。
+
+## Frontmatter
+
+每页必填：
+
+| 字段     | 类型   | 说明                            |
+|----------|--------|---------------------------------|
+| title    | string | 页面标题                        |
+| created  | date   | ISO 日期，创建时定死            |
+| updated  | date   | ISO 日期，每次编辑必须 bump     |
+| type     | string | 页面类型（note、source、moc 等）|
+| tags     | list   | `[a, b]`                        |
+
+来源页（`type: source` 或位于 `sourceDir` 下）额外必填：
+
+| 字段       | 类型   | 说明                                    |
+|------------|--------|-----------------------------------------|
+| source_url | string | 原始 URL                                 |
+| ingested   | date   | 抓取时间                                 |
+| sha256     | string | 抓取时正文哈希——日后借此发现来源被静默篡改 |
+
+可选 provenance 字段：
+
+| 字段             | 类型   | 说明                                          |
+|------------------|--------|-----------------------------------------------|
+| confidence       | float  | 0–1；低于下限（默认 0.5）会被标记             |
+| provenance_state | enum   | `extracted \| merged \| inferred \| ambiguous`|
+| contradicted_by  | list   | 与本页结论相左的页面 slug 列表                |
+
+## 矛盾标记
+
+两页观点冲突时，冲突必须显性化，不允许悄悄改写：
+
+1. 正文 callout：`> [!contradiction] 参见 [[other-page]] 持相反观点`
+2. Frontmatter 镜像：`contradicted_by: [other-page]`
+
+linter 的 `provenance.contradicted` 规则要求两处齐备——只有 callout 或只有
+frontmatter 都会被标记，因为机器读后者而人读前者。
+
+## 检查你的知识库
+
+```bash
+npx trustwiki lint ./your-vault
+```
+
+配置位于 vault 根目录 `.trustwiki.json`（所有键可选）：
+
+| 键                  | 默认值   | 含义                                   |
+|---------------------|----------|----------------------------------------|
+| roots               | `["."]`  | 参与扫描的目录                         |
+| index               | `null`   | 索引文件；声明后启用索引漂移规则       |
+| sourceDir           | `null`   | 引用路径解析根                         |
+| typeByDir           | `{}`     | 顶层目录对应的期望 type                |
+| minOutboundLinks    | `2`      | 孤页阈值                               |
+| inferredThreshold   | `0.3`    | 未引用散文段落占比上限                 |
+| confidenceFloor     | `0.5`    | 最低置信度                             |
+| inferredSkipTypes   | `["source"]` | 豁免推断占比的页面类型             |
+| rules               | 全开     | 逐规则 `error \| warn \| off`          |
+
+规则 id：`frontmatter.required`、`frontmatter.fields`、`placeholder.present`、
+`link.broken`、`link.index-missing`、`link.type-mismatch`、`page.orphan`、
+`citation.malformed`、`citation.target-missing`、
+`provenance.excess-inferred`、`provenance.low-confidence`、
+`provenance.contradicted`。
+
+退出码：`0` 干净（允许警告）、`1` 存在 error、`2` 配置或用法错误。

package/templates/demo-vault/.trustwiki.json

@@ -0,0 +1,6 @@
+{
+  "roots": ["notes", "sources"],
+  "index": "index.md",
+  "sourceDir": "sources",
+  "rules": { "page.orphan": "off" }
+}

package/templates/demo-vault/index.md

@@ -0,0 +1,7 @@
+# Demo vault
+
+- [[notes/honest-page]] — cited example
+- [[notes/sloppy-page]] — the patient
+- [[notes/conflict-a]] — contradiction side A
+- [[notes/conflict-b]] — contradiction side B
+- [[sources/tea]] — raw source

package/templates/demo-vault/notes/conflict-a.md

@@ -0,0 +1,13 @@
+---
+title: Conflict A
+created: 2026-09-05
+updated: 2026-09-05
+type: note
+tags: [demo]
+---
+
+# Conflict A
+
+Tea should be brewed at 100°C.^[sources/tea.md]
+
+> [!contradiction] 参见 [[notes/conflict-b]] 持相反观点

package/templates/demo-vault/notes/conflict-b.md

@@ -0,0 +1,12 @@
+---
+title: Conflict B
+created: 2026-09-05
+updated: 2026-09-05
+type: note
+tags: [demo]
+contradicted_by: [notes/conflict-a]
+---
+
+# Conflict B
+
+Tea should be brewed at 80°C.^[sources/tea.md]