Step 1: AI-Output sediment system (writeback + stale sweep) + bilingual user guide

[2233admin]

What this adds

The "persona outputs survive the session" design — Step 1 of the dependency chain ③ writeback → ① provenance → ② active-push. Without this, every /vault-architect / /vault-gardener / etc. analysis evaporates at session end; the vault only sediments the human's notes, not the collaboration history.

Two new MCP ops

vault.writeAIOutput

Persona calls this to persist a meaningful analysis. Lands at:

{vault}/00-Inbox/AI-Output/{persona}/YYYY-MM-DD-{slug}.md

With a 6-field frontmatter that a future sweep (or human) can reason about:

---
generated-by: vault-architect
generated-at: 2026-04-21T14:32:00.000Z
agent: claude-opus-4-7
parent-query: "refactor authentication module"
source-nodes:
  - "[[auth-architecture]]"
  - "[[session-tokens]]"
status: draft
---

Each field solves a distinct future-failure class: who / when / what-quality / why / from-where / still-valid. Every persona's skill file got a per-persona invocation template appended.

vault.sweepAIOutput

Gardener calls this to manage the sediment lifecycle. Two report types:

• Stale candidates — drafts past per-persona age threshold (architect=45d, gardener=30d, historian=180d, others=60d) AND with zero backlinks from non-AI-Output files. AI-Output → AI-Output references are self-anchoring hallucination chains and do not count.
• Supersede candidates — reviewed pairs with source-nodes Jaccard ≥ 0.6 and a newer generated-at. Reported only; never auto-applied.

dry_run: true (default) returns the report without writing. dry_run: false flips status: draft → stale in-place via narrow regex substitution (body + other fm fields preserved).

Design rationale (condensed)

• B → A lifecycle (gardener auto-stale + human manual-review) beats the reverse. Maintenance cost of "default trust + auto-stale" is O(误判 rate); cost of "default suspect + human promotes" is O(total volume). At 300 AI-Output files in 6 months you'll only promote ~5.
• Backlink filter excludes AI-Output sources because two AI-Output files can happen to cite each other without either being grounded in anything a human cared about. Forces at least one "this was worth keeping" vote from a human-written note.
• Supersede stays human-confirmed — auto-applying "this new one replaces that old one" would be AI grading its own successors, a second hallucination layer. Gardener proposes, human decides.
• Per-persona subdirs for MVP simplicity; schema carries enough info to graduate to flat + yaml-lookup without code changes if per-content-type differentiation proves more important than per-persona later.

Install + try it

New comprehensive bilingual guide lands in this PR:

• docs/GUIDE.md — English user journey walkthrough, 268 lines
• docs/GUIDE.zh-CN.md — 简体中文镜像，268 lines

Minimum viable try after merge:

git clone --depth 1 https://github.com/2233admin/obsidian-llm-wiki.git ~/obsidian-llm-wiki-src
cd ~/obsidian-llm-wiki-src && git checkout feat/ai-output-sediment && ./setup

Then in Claude Code: /vault-architect suggest 3 refactors for my vault structure. Watch the file appear at 00-Inbox/AI-Output/vault-architect/YYYY-MM-DD-suggest-3-refactors.md.

Verification

• npm run build — tsc 0 errors
• node.exe --test dist/**/*.test.js — 98 tests pass, 0 fail (88 baseline + 10 new)
• npm run generate-tools-doc — deterministic output; drift guard green

New tests cover the full contract:

Scenario	Covered
dryRun=false writes all 6 frontmatter fields + status: draft	✅
dryRun default returns plan without writing	✅
Collision appends -2 suffix same day/slug	✅
Invalid persona rejected with code -32602	✅
Empty sourceNodes serializes as []	✅
Stale detection uses injected now for determinism	✅
Drafts with non-AI-Output backlinks are exempted	✅
AI-Output → AI-Output backlinks do NOT anchor	✅
dry_run: false flips status in-place, preserves body	✅
Supersede candidates fire on Jaccard ≥ 0.6	✅

Incidental fixes included

• class VaultFs is now exported from mcp-server/src/index.ts (was module-private).
• main() now guarded by import.meta.url === process.argv[1]. Without this, importing VaultFs from tests would spin up StdioServerTransport and hold stdin open, blocking all subsequent test files. One-liner, preserves runnable-as-entrypoint behavior.

Files modified

• mcp-server/src/core/operations.ts — 2 new Operation entries (+27)
• mcp-server/src/index.ts — 2 dispatch cases + export + main guard (+190)
• mcp-server/src/ai-output.test.ts — NEW, 10 tests (+297)
• skills/vault-{architect,curator,gardener,historian,janitor,librarian,teacher}.md — +17 each (gardener +23)
• docs/ai-output-convention.md — NEW schema + lifecycle + FAQ (~120)
• docs/mcp-tools-reference.md — auto-regenerated (+29)
• docs/GUIDE.md + docs/GUIDE.zh-CN.md — NEW bilingual guide (268 each)
• README.md — language-switch blockquote above description
• progress.txt — Step 1 shipping summary + handoff

Explicitly deferred

• Auto reviewed → superseded flip (currently reports only)
• YAML-config stale policy (currently hardcoded)
• user-verdict frontmatter field
• Provenance enrichment of other MCP op responses (Step 2 in the dependency chain)

Ready for review or merge. Base is v2-staging so this layers on top of PR #4 — merge order: #4 first, then this.

[gemini-code-assist]

Code Review

This pull request introduces the 'AI-Output sediment' feature, which allows persona-authored analyses to be persisted in the vault. It adds two new MCP tools: vault.writeAIOutput for saving analyses with structured frontmatter and vault.sweepAIOutput for managing the lifecycle of these files (staling old drafts and identifying supersede candidates). The PR also includes comprehensive documentation, unit tests, and updates to persona skill files to utilize the new writeback capability. Feedback focuses on optimizing the sweep operation's performance and ensuring YAML frontmatter integrity by sanitizing newlines in user-provided strings.

[gemini-code-assist]

The current implementation of hasRealBacklink is highly inefficient as it performs a full vault scan (this.walkMd) for every AI-Output draft found. In a vault with $N$ total files and $M$ AI-Output drafts, this results in $O(M \times N)$ file read operations. For large vaults, this will cause significant performance degradation during the sweep operation.

It is recommended to build a set of all human-authored wikilinks by walking the vault once before iterating through the AI-Output entries.

        // Pre-compute all human-authored links to avoid O(M*N) vault scans
        const humanLinks = new Set<string>();
        this.walkMd((relPath, content) => {
          if (aiOutputPaths.has(relPath)) return;
          for (const l of this.parseWikilinks(content)) {
            const link = l.link.split("#")[0];
            if (link) humanLinks.add(link);
          }
        });

        const hasRealBacklink = (targetRel: string): boolean => {
          const targetBase = basename(targetRel, ".md");
          const targetNoExt = targetRel.replace(/\.md$/, "");
          return humanLinks.has(targetRel) || humanLinks.has(targetBase) || humanLinks.has(targetNoExt);
        };

[gemini-code-assist]

The parentQuery string is embedded directly into the YAML frontmatter. If the user's query contains newlines, it will break the simple line-based frontmatter parser implemented in parseFrontmatter (which splits by \n and expects key: value pairs). Sanitizing newlines by replacing them with spaces ensures the generated file remains valid and parseable.

Suggested change

	const parentQuery = parentQueryRaw.slice(0, 200).replace(/"/g, "\u201D");
	const parentQuery = parentQueryRaw.slice(0, 200).replace(/"/g, "\u201D").replace(/\n/g, " ");

[gemini-code-assist]

Similar to parentQuery, items in sourceNodes should be sanitized for newlines to prevent breaking the YAML frontmatter structure during serialization, especially since these values are provided by the LLM and might contain unexpected formatting.

Suggested change

	const escaped = String(node).replace(/"/g, "\u201D");
	const escaped = String(node).replace(/"/g, "\u201D").replace(/\n/g, " ");