@creativeaitools/agent-wiki 2.0.0

package/skills/process-inbox/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: process-inbox
+description: "Process raw files dropped into the Agentics vault inbox. Use this skill whenever the user says \"process inbox\", \"check the inbox\", \"handle new notes\", \"process raw notes\", \"ingest inbox files\", or wants to convert raw files in _inbox/ into canonical source pages."
+---
+
+# Process Inbox
+
+This skill promotes raw files from `_inbox/` into canonical, schema-compliant `source` pages. It does not extract entities, concepts, claims, questions, or relations; use `skills/extract-knowledge-primitives/SKILL.md` after source pages exist.
+
+## Step 1: Read the Vault Contract
+
+Before touching anything, read the vault's agent contract in this order:
+
+1. `AGENTS.md` - the behavioral contract.
+2. `WIKI.md` Sections 4.1, 5, 12, and 13 - the runtime source schema, status/source type enums, ID formats, examples, and large-source rules.
+3. `WIKI.md` Section 14 - the durable raw inbox lifecycle.
+
+Key rules for this workflow:
+- Preserve raw content.
+- Use stable source IDs.
+- Do not invent metadata.
+- Use `WIKI.md` Section 4.1 for source page schema, examples, and conversion provenance fields.
+- Use `WIKI.md` Sections 5 and 12 for status values and source types.
+- Use `WIKI.md` Section 13 for large-source parent and part handling.
+- Use `agent-wiki create-page` to write canonical source pages and source part pages.
+- Use `AGENT-WIKI-SPEC-v2.md` only when changing project behavior, resolving ambiguity, or when `WIKI.md` Sections 4.1, 5, 12, or 13 are insufficient.
+  Use `AGENT-WIKI-SPEC-v2.md` Section 6.10 only when you need the page scaffolding contract or `agent-wiki create-page` option semantics.
+
+If local Python or converter availability is unknown, run the read-only onboarding probe before processing binary or non-markdown files:
+
+```bash
+agent-wiki onboard --check
+```
+
+For first-run setup decisions, prefer:
+
+```bash
+agent-wiki onboard --check --questions
+```
+
+Use the generated multiple-choice prompts so the user can answer with compact letter choices.
+
+Use the probe output and `_system/config.json`, when present, to determine which local conversion backends are configured and available. Also use the probe output to understand OS/platform, whether the repository root has local Obsidian settings, and whether local `knownVaults` mappings exist for `obsidian://` references. `_system/config.example.json` is the tracked example shape; `_system/config.json` is local-only policy.
+
+If the user approves persisting local Python or conversion policy, write local config with explicit approved flags:
+
+```bash
+agent-wiki onboard --write-config --python-command python3 --conversion disabled
+```
+
+This checkout is the only wiki root. Process `_inbox/`, write `sources/`, and move retained raw files to `raw/` relative to the repository root. Do not accept an alternate vault root or external destination for this workflow.
+
+Do not create a virtual environment, install packages, write `_system/config.json`, or create unrelated setup folders unless the user explicitly asks for that setup work. Creating the target source directories and `raw/` as part of an approved inbox promotion is allowed. Do not hand-edit `_system/config.json`; use `agent-wiki onboard --write-config` after approval.
+
+If an inbox item contains an `obsidian://` URI, follow `AGENT-WIKI-SPEC-v2.md` Section 8.6. Do not launch the URI. Resolve it only through `_system/config.json` `knownVaults`, and otherwise preserve it as an opaque external reference.
+
+## Step 2: Check the Inbox
+
+Scan `_inbox/` for raw files. Ignore directories and hidden/system files. Do not treat `_inbox/trash/` or `raw/` as active queue locations.
+
+If `_inbox/` is empty or contains no processable raw files, report that and stop.
+
+## Step 3: Promote Each Raw File
+
+For each raw file, work through files one at a time.
+
+### 3a. Read the raw file
+
+Read the file fully. Preserve the original content exactly when writing the source body.
+
+If the raw file is plain text or Markdown, treat the raw file itself as the prepared source body file. Prefer passing that file directly to `agent-wiki create-page` with `--body-file` unless the source needs partitioning. Do not copy text or Markdown inbox content into `--body`.
+
+If the raw file is a binary or non-markdown document, use configured local conversion tools only when they are available. Read conversion policy from `_system/config.json` if it exists. Missing config means use conservative local-only defaults.
+
+Do not install dependencies during this skill run. Do not call network, cloud OCR, LLM, transcription, or hosted document-intelligence services unless the operator explicitly configured or requested that behavior.
+
+If no configured conversion path exists, leave the file in `_inbox/` and report that text extraction is required.
+
+When conversion is used, record conversion provenance in the source frontmatter when available:
+
+- `convertedAt`
+- `conversionTool`
+- `conversionToolVersion`
+- `conversionBackend`
+- `conversionWarnings`
+
+### 3b. Infer source metadata
+
+Create source pages using `agent-wiki create-page`. The scaffolder writes schema-compliant source pages, validates source parent/part requirements, and prevents duplicate IDs or target path overwrites.
+
+Newly promoted ordinary source pages MUST use `status: unprocessed` and `sourceRole: whole`. The extraction workflow changes source pages to `status: processed` after knowledge primitives have been extracted.
+
+Large source parent pages MUST use `sourceRole: parent`. They SHOULD use `status: partitioned` while one or more child source parts remain unprocessed. Child source part pages MUST use `sourceRole: part` and `status: unprocessed`.
+
+Use this ID pattern:
+
+```text
+source.<yyyy-mm-dd>.<sourceType>.<sourceSlug>
+```
+
+- `yyyy-mm-dd`: processing date unless the raw file clearly includes a retrieval date.
+- `sourceType`: the inferred source type from `WIKI.md` Section 12.
+- `sourceSlug`: short kebab-case descriptor, preferably four words.
+
+Infer `sourceType` conservatively:
+- YouTube transcript -> `transcript`
+- Article or blog post -> `article`
+- PDF -> `pdf`
+- Long generic document -> `document`
+- Email -> `email`
+- Meeting notes -> `meeting-notes`
+- Raw data -> `dataset`
+- Screenshot -> `screenshot`
+- Unknown or plain notes -> `other`
+
+If a field such as `publishedAt`, `author`, or `originUrl` cannot be inferred, omit optional fields rather than guessing. For local raw files with no external URL, use `originPath` to record the retained raw file path after promotion. Required source fields must still follow `WIKI.md` Section 4.1.
+
+### 3c. Decide whether to partition
+
+If the captured or converted text is larger than roughly 25,000 words, or if an agent cannot reliably process it in one extraction pass, create a large source instead of one giant markdown body.
+
+Use deterministic split rules from `WIKI.md` Section 13:
+
+- prefer semantic boundaries such as chapters, headings, appendices, transcript topics, or slide boundaries
+- fall back to page ranges, timestamps, or other stable locators
+- target 8,000-15,000 words per source part
+- do not exceed 20,000 words per part unless preserving an indivisible structure requires it
+- avoid splitting inside tables, code blocks, quoted blocks, or list structures when possible
+
+For ordinary sources, write one canonical source page.
+
+For large sources, write:
+
+- one parent source page under `sources/`
+- child source part pages under `sources/parts/`
+
+### 3d. Write the source page or source parts
+
+Before writing the source page, determine the final retained raw path that will be used after promotion:
+
+```text
+raw/<yyyy-mm-dd>-<source-slug>-original<extension>
+```
+
+Use that future retained path as `--origin-path` when calling the scaffolder. If a filename already exists, choose the collision-resistant retained filename before creating the source page.
+
+For an ordinary source, save the prepared verbatim Markdown body to a temporary file outside the vault, then call:
+
+For `.md` or `.txt` inbox files that do not need conversion or cleanup, the prepared source body may be the raw inbox file itself. For converted binary files, use the converted Markdown output file. Always prefer `--body-file` for source bodies.
+
+```bash
+agent-wiki create-page \
+  --type source \
+  --subtype <sourceType> \
+  --slug <sourceSlug> \
+  --title "<title>" \
+  --source-date <yyyy-mm-dd> \
+  --retrieved-at <yyyy-mm-dd> \
+  --origin-path "raw/<retained-filename>" \
+  --source-role whole \
+  --body-file <prepared-source-body.md> \
+  --no-log
+```
+
+The body file must contain the full verbatim raw or converted content below the frontmatter. Preserve user context, annotations, and formatting.
+
+For a large source, save each prepared segment body and the short parent manifest body to temporary Markdown files outside the vault. Call the scaffolder once for each child source part, then once for the parent manifest.
+
+Part pages use:
+
+```bash
+agent-wiki create-page \
+  --type source \
+  --subtype <sourceType> \
+  --slug <sourceSlug> \
+  --title "<title> - Part <n>" \
+  --source-date <yyyy-mm-dd> \
+  --retrieved-at <yyyy-mm-dd> \
+  --origin-path "raw/<retained-filename>" \
+  --source-role part \
+  --parent-source-id <parentSourceId> \
+  --part-index <n> \
+  --part-count <count> \
+  --locator "<locator>" \
+  --body-file <prepared-source-part-body.md> \
+  --no-log
+```
+
+Parent pages use:
+
+```bash
+agent-wiki create-page \
+  --type source \
+  --subtype <sourceType> \
+  --slug <sourceSlug> \
+  --title "<title>" \
+  --source-date <yyyy-mm-dd> \
+  --retrieved-at <yyyy-mm-dd> \
+  --origin-path "raw/<retained-filename>" \
+  --source-role parent \
+  --source-part sources/parts/<yyyy-mm-dd>-<sourceType>-<sourceSlug>-part001.md \
+  --part-count <count> \
+  --body-file <prepared-parent-manifest-body.md> \
+  --no-log
+```
+
+Repeat `--source-part` once for each ordered child part path.
+
+The parent body should stay short and should not contain the full long-form source text. Include metadata, import notes, attachment references, retained raw path, and an ordered source part manifest. Each part body must contain the verbatim text for that segment.
+
+### 3e. Move the raw file
+
+After the source page is created successfully, move the original raw file from `_inbox/` to `raw/` so it is no longer in the active inbox queue. A raw file that has been promoted into a canonical `source` page MUST NOT remain in `_inbox/`.
+
+Use a collision-resistant retained filename:
+
+```text
+raw/<yyyy-mm-dd>-<source-slug>-original<extension>
+```
+
+If a filename already exists, append a short unique suffix before the extension.
+
+The source page's `originPath` should match the final retained raw file path. For large sources, the parent and all child source parts should use the retained raw path as `originPath`.
+
+If source page creation succeeds but moving the raw file fails, report the move failure clearly and leave the source page in place. Do not process the same inbox file again until the raw file lifecycle has been resolved.
+
+If a raw file cannot be promoted, leave it in `_inbox/` and report the reason. Do not silently move failed items.
+
+## Step 4: Report to the User
+
+If one or more raw files were promoted, write one operational log entry for the processed batch:
+
+```bash
+agent-wiki log --message "process-inbox: promoted <count> raw files to sources; skipped=<count> failed=<count>"
+```
+
+Do not write a log entry when no files were promoted.
+
+After processing all items, give a concise summary:
+
+- How many raw files were promoted.
+- The source path and ID for each promoted file.
+- For large sources, the parent source path and each child part path.
+- The retained raw path for each original.
+- Any files skipped or failed and why.
+
+## Important Rules
+
+- `_inbox/` is an active raw drop zone, not canonical knowledge.
+- `raw/` retains original raw captures after promotion and is not canonical knowledge.
+- `sources/` contains the canonical verbatim source pages.
+- Large source parent pages are metadata and manifests; extraction should operate on source parts.
+- Do not create separate intake tracking files.
+- Do not extract knowledge primitives in this skill.
+- Do not touch human prose except to preserve it verbatim in the new source page body.

package/skills/process-workspace-sources/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: process-workspace-sources
+description: "Process workspace-mode source candidates discovered outside the wiki directory. Use this when the user asks to process workspace files, scan workspace sources, or promote changed workspace files into canonical source pages."
+---
+
+# Process Workspace Sources
+
+This skill promotes selected files from a workspace into canonical `source` pages inside the workspace wiki. It is the workspace-mode counterpart to `process-inbox`, but it does **not** move, rewrite, archive, or otherwise modify the original workspace files.
+
+## Step 1: Read the Contract
+
+Before touching anything, read:
+
+1. `AGENTS.md`
+2. `WIKI.md` Sections 4.1, 5, 12, and 13
+3. `AGENT-WIKI-SPEC-v2.md` only when changing behavior or resolving ambiguity
+
+Key rules:
+
+- The source files belong to the workspace owner. Leave them in place.
+- Workspace files are discovery inputs, not canonical evidence until represented by `sources/` pages.
+- Canonical source pages live inside the wiki directory, usually `wiki/sources/`.
+- Use `agent-wiki create-page` from the wiki root to create source pages.
+- New source pages use `status: unprocessed` and `sourceRole: whole` unless partitioned.
+- Large source parent/part behavior matches the existing source schema.
+
+## Step 2: Get the Workspace Worklist
+
+From the project root, list new or changed non-code source candidates:
+
+```bash
+agent-wiki workspace pending --workspace-root . --json
+```
+
+If the console script is not installed yet, build and link the local package first:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+The command returns an agent-readable list with:
+
+- workspace-relative path
+- absolute path
+- modified time
+- size
+- sha256
+- reason (`new` or `changed`)
+- recommended source type
+- existing source mapping, when known
+
+Use `workspace scan --write-state` only when you intentionally want to refresh the local scan state after reviewing the candidate set.
+
+## Step 3: Select Files To Promote
+
+For each pending file, decide whether it should become a canonical source page.
+
+Skip files that are:
+
+- generated output
+- local configuration
+- dependency/cache/build artifacts
+- source code or scripts
+- temporary notes not worth durable source treatment
+
+If a file is already represented by a source page and only changed, update or supersede the source page only when the user wants changed source content reflected in the wiki. Do not silently overwrite an existing source body.
+
+## Step 4: Create Canonical Source Pages
+
+For each selected file:
+
+1. Read the workspace file in place.
+2. Infer conservative metadata.
+3. Create a source page in the wiki with `agent-wiki create-page`.
+4. Set `originPath` to the workspace-relative path of the original file.
+5. Do not move or modify the original workspace file.
+
+For a normal text or Markdown source, from the wiki root:
+
+```bash
+agent-wiki create-page \
+  --type source \
+  --subtype <sourceType> \
+  --slug <sourceSlug> \
+  --title "<title>" \
+  --source-date <yyyy-mm-dd> \
+  --retrieved-at <yyyy-mm-dd> \
+  --origin-path "<workspace-relative-path>" \
+  --source-role whole \
+  --body-file "<absolute-or-relative-workspace-file>" \
+  --no-log
+```
+
+For large files, use the same parent/source-part pattern as `process-inbox`, but `originPath` remains the workspace-relative path and there is no `raw/` retained-file move.
+
+## Step 5: Update Workspace State
+
+After successful promotion, record the mapping from workspace file to source page:
+
+```bash
+agent-wiki workspace mark-sourced \
+  --workspace-root . \
+  --path "<workspace-relative-path>" \
+  --source-id "<sourceId>" \
+  --source-path "sources/<source-file>.md"
+```
+
+If the console script is not installed yet, build and link the local package with `npm install && npm run build && npm link`.
+
+The command writes `wiki/_system/state/workspace-sources.json`. This state file is local generated state and should not be treated as canonical knowledge.
+
+## Step 6: Continue The Existing Pipeline
+
+After source pages exist:
+
+1. Run `extract-knowledge-primitives` to process `status: unprocessed` source pages.
+2. Run `compile-wiki` to regenerate caches, indexes, reports, and root catalog.
+
+## Important Rules
+
+- Workspace mode has no raw-file lifecycle.
+- Do not move files to `raw/`.
+- Do not use `_inbox/` for workspace discovery unless the user explicitly placed files there.
+- Do not treat discovered workspace files as evidence until a canonical source page exists.
+- Do not modify the original workspace file.

package/skills/update-overview/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: update-overview
+description: "Create or refresh the root overview.md landing page for the vault. Use this skill when the user asks to update the vault overview, create the landing page, summarize the vault, refresh overview.md, or produce a human-facing vault summary."
+---
+
+# Update Vault Overview
+
+This skill creates or refreshes root `overview.md`, the human-facing narrative landing page for the vault. It does not own the schema.
+
+Runtime overview schema lives in `WIKI.md` Section 4.1. Page type rules live in `WIKI.md` Section 3. Authority rules live in `WIKI.md` Sections 1.1, 9, and 11. The vault behavior contract lives in `AGENTS.md`. The full project/development contract lives in `AGENT-WIKI-SPEC-v2.md`.
+
+Use `AGENT-WIKI-SPEC-v2.md` only when changing project behavior, resolving ambiguity, or when `WIKI.md` Sections 1.1, 3, 4.1, 9, or 11 do not contain enough detail. If this skill or those `WIKI.md` sections conflict with `AGENT-WIKI-SPEC-v2.md`, follow `AGENT-WIKI-SPEC-v2.md`.
+
+## When to Use
+
+Use this skill when:
+- the user asks for a vault overview, vault landing page, or root `overview.md`
+- the vault has changed meaningfully and the human-facing overview should be refreshed
+- the user wants a paragraph-form summary of the vault and its page types
+
+Do not run this skill automatically as part of compile. `overview.md` is durable AI-maintained prose, not a deterministic compile artifact.
+
+## Step 1: Read the Contract and Runtime Reference
+
+Before updating `overview.md`, read:
+
+1. `AGENTS.md` for behavior rules.
+2. `WIKI.md` Sections 3, 4.1, 9, and 11 for the `overview.md` page type, runtime schema, generated-content authority, and report authority.
+
+Read `AGENT-WIKI-SPEC-v2.md` only when changing the project itself, resolving ambiguity, or when `WIKI.md` Sections 1.1, 3, 4.1, 9, or 11 are insufficient.
+
+## Step 2: Compile First
+
+Run compile before writing the overview so cache inputs are current:
+
+```bash
+agent-wiki compile
+```
+
+If compile reports validation issues, fix or report those issues before relying on generated cache data for the overview.
+
+## Step 3: Gather Inputs
+
+Use compiled and canonical inputs, in this order:
+
+1. `_system/cache/pages.json` for page inventory, page types, titles, statuses, paths, and metadata.
+2. `_system/cache/agent-digest.json` for compact high-signal context.
+3. `_system/cache/relations.jsonl` for explicit cross-page links, relation types, and densely connected subgraphs — used to derive topical clusters.
+4. Canonical pages in content folders when the overview needs richer context than the cache provides.
+5. Root docs such as `README.md`, `WIKI.md` Sections 1.1 and 2, and `INBOX.md` for project and workflow orientation.
+
+Do not use reports or logs as primary truth. Reports may help identify maintenance concerns, but the overview should be grounded in canonical pages and compiled cache data.
+
+## Step 4: Create or Refresh `overview.md`
+
+Write `overview.md` at the vault root.
+
+If the file does not exist, create it with frontmatter using the universal and overview fields from `WIKI.md` Section 4.1:
+
+```yaml
+id: meta.overview
+pageType: overview
+title: Vault Overview
+status: active
+```
+
+Set `createdAt` and `updatedAt` using `YYYY-MM-DD`. Include `aliases` and `tags` as required by the spec.
+
+If the file already exists:
+- preserve any human-authored prose unless the user explicitly asks for a rewrite
+- update `updatedAt` when the overview prose or frontmatter changes
+- keep `pageType: overview`
+- keep the file at root `overview.md`
+
+## Step 5: Write the Overview
+
+Write in long-form article style for a human reader.
+
+The overview should include:
+- a vault-level summary
+- paragraph-form summaries for each active page type represented in the vault
+- a detailed cluster analysis (see below)
+- clear orientation about what the reader can find and where the material lives
+- an honest account of sparse, draft, or incomplete areas when the vault is small or early-stage
+
+Use headings sparingly and make the page readable as a landing article, not a generated table or report.
+
+### Cluster Analysis Section
+
+The overview MUST include a dedicated section that groups vault pages into meaningful topical clusters. A cluster is a set of related pages that share a common subject, entity, theme, or research thread — regardless of their individual page type.
+
+To derive clusters:
+
+1. Read the titles, tags, and relations fields from `_system/cache/pages.json`.
+2. Read `_system/cache/relations.jsonl` for explicit cross-page links and relation types.
+3. Group pages by shared subject matter, named entities, recurring themes, or densely connected subgraphs.
+4. Name each cluster after its dominant topic or entity (e.g., "Urban Water Infrastructure", "Key Decision-Makers", "Unanswered Questions About X").
+5. Write a paragraph for each cluster that:
+   - describes what the cluster is about and why these pages belong together
+   - names the most important or representative pages using wikilinks
+   - notes the mix of page types present (sources, claims, entities, syntheses, etc.)
+   - identifies open questions or gaps within the cluster, if any
+
+If the vault has fewer than five pages, describe the emerging clusters as early-stage threads rather than omitting the section.
+
+Do not invent clusters that are not grounded in actual page content. If pages are too sparse to cluster meaningfully, say so honestly.
+
+When referring to specific vault pages — entities, sources, concepts, claims, syntheses, questions, or any other canonical page — use Obsidian-style wikilinks (`[[page-slug]]` or `[[page-slug|Display Text]]`). Do not use plain text names, standard markdown links, or bare file paths for internal vault references. This applies to every page mentioned in the overview body, including examples, highlights, cluster descriptions, and section summaries.
+
+Do not make unsupported claims about the vault. If the cache shows no pages for a page type, either omit that page type or describe it as a supported structure that currently has no active pages, depending on what best serves the reader.
+
+## Step 6: Authority Rules
+
+`overview.md` is orientation, not evidence.
+
+Do not:
+- treat `overview.md` as primary evidence for claims
+- place claim/evidence records only in the overview
+- use the overview to replace canonical source, entity, concept, claim, synthesis, or question pages
+- regenerate it mechanically on every compile run
+
+If the overview describes a substantive claim that should be tracked, create or update the appropriate canonical page or claim record instead of leaving the claim only in overview prose.
+
+## Step 7: Log the Update
+
+After successfully creating or refreshing `overview.md`, write one operational log entry:
+
+```bash
+agent-wiki log --message "update-overview: refreshed root overview.md; pageTypes=<count> pages=<count>"
+```
+
+Do not write a log entry if no file was changed.
+
+## Step 8: Report Results
+
+Report a concise summary:
+- whether `overview.md` was created or refreshed
+- which inputs were used
+- whether compile had validation issues
+- any notable gaps, such as missing summaries or sparse page types

package/skills/write-synthesis/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: write-synthesis
+description: "Create or refresh durable synthesis pages. Use this skill when the user asks to synthesize sources, write a brief, compare documents, summarize a research thread, create an analysis, or make a timeline synthesis."
+---
+
+# Write Synthesis
+
+This skill creates or refreshes `synthesis` pages in `syntheses/`. It owns judgment and prose for cross-source interpretation. It does not own the vault schema or deterministic file scaffolding.
+
+Runtime synthesis schema lives in `WIKI.md` Section 4.1. Page type rules live in `WIKI.md` Section 3. Status enums live in `WIKI.md` Section 5. Evidence rules live in `WIKI.md` Section 7. Synthesis workflow rules live in `AGENT-WIKI-SPEC-v2.md` Section 10.5. The vault behavior contract lives in `AGENTS.md`.
+
+Use `AGENT-WIKI-SPEC-v2.md` only when changing project behavior, resolving ambiguity, or when `WIKI.md` Sections 3, 4.1, 5, or 7 do not contain enough detail. If this skill or those `WIKI.md` sections conflict with `AGENT-WIKI-SPEC-v2.md`, follow `AGENT-WIKI-SPEC-v2.md`.
+
+Use Obsidian wikilinks for references inside this vault. For cross-vault Obsidian references, use standard markdown links with `obsidian://` URIs per `AGENT-WIKI-SPEC-v2.md` Section 8.6. Do not launch `obsidian://` URIs; resolve them only through local `_system/config.json` `knownVaults`, and treat unconfigured vaults as opaque external references.
+
+## When to Use
+
+Use this skill when the user asks to:
+- synthesize multiple sources or pages
+- write a brief, analysis, comparison, summary, or timeline synthesis
+- compare documents, sources, positions, or claims
+- summarize a research thread into durable authored knowledge
+- maintain an existing synthesis after new sources or claims are added
+
+Do not use this skill for:
+- atomic propositions that should be claim pages
+- verbatim captured material that should be source pages
+- unresolved unknowns that should be question pages
+- deterministic maintenance output that should be reports
+- whole-vault landing prose that should be root `overview.md`
+
+## Step 1: Read the Contract and Runtime Reference
+
+Before writing or refreshing a synthesis, read:
+
+1. `AGENTS.md` for behavior rules.
+2. `WIKI.md` Sections 3, 4.1, 5, and 7 for page types, runtime schema, status values, and evidence rules.
+3. `AGENT-WIKI-SPEC-v2.md` Section 10.5 for synthesis workflow rules.
+
+## Step 2: Compile or Inspect Current Cache
+
+If the synthesis depends on current vault inventory, run compile first:
+
+```bash
+agent-wiki compile
+```
+
+If the user asks for a narrow synthesis over explicitly named files and the needed pages are already known, compile is optional. Do not rely on reports or logs as primary truth.
+
+## Step 3: Select Inputs
+
+Use canonical inputs in this order:
+
+1. Explicit source pages, source part pages, claim pages, entities, concepts, or questions named by the user.
+2. `_system/cache/pages.json`, `_system/cache/claims.jsonl`, and `_system/cache/source-index.json` for discovery.
+3. Canonical pages in `sources/`, `claims/`, `entities/`, `concepts/`, `questions/`, and existing `syntheses/` when richer context is needed.
+
+For large sources, prefer source part pages over parent source manifests when the relevant evidence comes from a specific part.
+
+## Step 4: Decide Whether to Create or Update
+
+Search `syntheses/` and `_system/cache/pages.json` for an existing synthesis with the same scope, audience, and synthesis type.
+
+Update an existing synthesis when it already covers the requested scope. Create a new synthesis when the scope, time horizon, audience, or analytical question is materially different.
+
+Choose `synthesisType` from `WIKI.md` Section 4.1:
+- `summary` for compact cross-source restatements
+- `overview` for broad topic orientation
+- `analysis` for reasoned interpretation
+- `timeline` for chronological narrative
+- `brief` for decision-relevant summary
+- `comparison` for side-by-side interpretation
+
+## Step 5: Write the Body
+
+Write substantive Markdown prose for a human reader. The body should normally include:
+- scope and purpose
+- source basis or coverage
+- main synthesis in paragraph form
+- important evidence, claims, or examples
+- uncertainty, limits, contradictions, or unresolved questions
+- current conclusion or next-step implication, when appropriate
+
+Preserve uncertainty. Do not present weak, incomplete, or contested evidence as established fact.
+
+If the synthesis introduces an important atomic proposition that needs independent evidence tracking, create or update a claim page and include that claim ID in `derivedClaims`.
+
+If the synthesis surfaces a durable unresolved issue, create or update a question page and reference it in the body or related fields.
+
+## Step 6: Create New Synthesis Pages
+
+For new synthesis pages, prepare the body prose in a temporary Markdown file outside the vault, then use the deterministic scaffolder:
+
+```bash
+agent-wiki create-page \
+  --type synthesis \
+  --subtype brief \
+  --slug <synthesis-slug> \
+  --title "<title>" \
+  --scope "<scope>" \
+  --source-page <sourceId> \
+  --derived-claim <claimId> \
+  --body-file <prepared-body.md> \
+  --no-log
+```
+
+Repeat `--source-page` and `--derived-claim` as needed. `--scope` is required.
+
+The scaffolder owns IDs, filename, required frontmatter, duplicate checks, and body placement. This skill owns source selection, synthesis type selection, body prose, uncertainty handling, and any claim or question updates.
+
+## Step 7: Refresh Existing Synthesis Pages
+
+When updating an existing synthesis:
+- preserve human-authored prose unless the operator explicitly asks for a rewrite
+- update `updatedAt` when prose or structured fields change
+- update `sourcePages` when the source basis changes
+- update `derivedClaims` when claim dependencies change
+- keep stale or contradicted prior context visible when it matters to the current interpretation
+
+Do not regenerate a synthesis mechanically on every compile run.
+
+## Step 8: Log the Synthesis Batch
+
+After successfully creating or refreshing one or more synthesis pages, write one operational log entry:
+
+```bash
+agent-wiki log --message "write-synthesis: updated <count> syntheses; sources=<count> claims=<count>"
+```
+
+Do not write a log entry when no synthesis page changed.
+
+## Step 9: Report Results
+
+Report a concise summary:
+- synthesis pages created or refreshed
+- source pages and claim pages used
+- questions or claims created or updated
+- notable uncertainty, contradictions, or gaps
+- whether compile reported validation issues
+
+## Checklist
+
+- [ ] Read `AGENTS.md`, `WIKI.md` Sections 3, 4.1, 5, and 7, and `AGENT-WIKI-SPEC-v2.md` Section 10.5
+- [ ] Identify the synthesis scope, audience, and `synthesisType`
+- [ ] Select canonical source pages, source parts, claims, and related pages
+- [ ] Check for an existing synthesis before creating a new one
+- [ ] Use `agent-wiki create-page --no-log` for new synthesis pages
+- [ ] Include required `--scope`
+- [ ] List source basis in `sourcePages` when sources are used
+- [ ] List tracked claim dependencies in `derivedClaims` when claims are used
+- [ ] Preserve uncertainty, contradictions, and important caveats
+- [ ] Create or update claim/question pages when needed
+- [ ] Write one operational log entry for the synthesis batch
+- [ ] Report results