Use with an AI assistant

You never have to organize anything yourself. That is the point of KnowFlow: a coding agent — ZCode, Codex CLI, Claude Code, OpenCode, anything that can read and write files — does the drafting, and you keep the judgment. All of them execute the same written contract, so swapping agents changes nothing.

The loop

you save ──► raw/ ──► agent synthesizes ──► you review ──► graph + search
              │         (one contract)        (one word)
              │
              └─ raw/ is never rewritten; pending pages stay out of the graph and index

1. Capture. Save an article, tweet, or note into raw/ — by running knowflow ingest yourself, or by asking your agent to do it. Capture never touches an LLM.
2. Synthesize. The agent follows the synthesis contract — materialized by knowflow init at docs/agents/synthesize.md in your workspace, with the AGENTS.md pointer section as the zero-config entry point (upstream master): one status: pending source page per raw file, minimal entity pages for newly seen entities, created_from provenance, (EXTRACTED)/(INFERRED) confidence markers, strict root-relative [[wikilinks]]. knowflow compose --list tells it exactly what is left to do.
3. Review. Approve a page by changing one word — pending to reviewed. Reject by deleting the file. Concept and comparison pages are synthesized only when you explicitly ask.
4. Validate & see. knowflow health and knowflow check verify the batch; knowflow graph and knowflow index build skip pending pages, so the graph and the search index only ever contain what you approved.

A prompt that works

Paste this into your agent to bootstrap it:

You maintain my KnowFlow wiki. Work in this project directory.

Read the KnowFlow synthesis contract at docs/agents/synthesize.md
in this workspace (materialized by knowflow init) and follow it exactly.

Task:
1. Run `knowflow compose --list` to see which raw files have no wiki page yet.
2. Synthesize them per the contract: `status: pending` source pages plus
   minimal entity pages, written straight into their final directories.
3. Run `knowflow health` and `knowflow check`; fix only pages you created
   in this batch. Never run `knowflow fix` without --dry-run.
4. Report what you created and which links you made, for my review.

(If a copy of the contract is available locally — a checkout of the knowflow repo, or a file you copied into the project — point the agent at that path instead of the URL.)

A worked example

Say you saved an article about retrieval-augmented generation:

• The agent creates wiki/sources/rag-article.md — a status: pending record of where it came from, with each key point marked (EXTRACTED) or (INFERRED).
• For entities the article introduces, it drafts minimal wiki/entities/… pages and links them from the source page’s 提取的实体 section. Existing entity pages are linked, never rewritten.
• No concept pages appear on their own — concepts are synthesized only when you explicitly ask (“build a concept page for RAG”).
• You review: flip the pages to reviewed, or delete one to reject. Only then do knowflow graph and knowflow index build pick them up.

Next month another RAG article arrives, and the agent drafts a second source page the same way — the graph grows denser. Content-level dedup across similar sources is on the roadmap; today, capturing the same URL twice yields two source pages by design.

Tips

• Small batches. The contract allows batch synthesis, but a handful of raw files per pass keeps review quick.
• Dry-run repairs. If health complains about pages you did not create, have the agent run knowflow fix --dry-run and show you — never a bare knowflow fix. The contract bans it: real fixes rewrite reviewed pages, and review is yours.
• Trust the gates. Pending pages are skipped by graph and index build, exempt from health’s orphan rule, and untouched by fix. Unreviewed work cannot leak into the graph or the search index.
• Swap agents freely. The contract is a plain Markdown file — ZCode, Codex CLI, Claude Code, and OpenCode read the same words and land in the same place.
• Keep Git on. git diff is your review screen — every synthesis pass is a readable, revertable diff.