ziki-add

Ziki Add

File content into the Ziki knowledge base inbox via the remote vault repository.

This skill is used both explicitly (user request or /ziki-add command) and autonomously (Stop/PreCompact hooks).

Synthesis vs ground truth — read this first

Every inbox entry has two layers, and you must capture both in the same pass:

1. Synthesis — the draft page you write. Your interpretation, summary, or explanation of a topic. Derived, interpretive, and potentially wrong. Goes into _inbox/<slug>.md.
2. Ground truth — the primary sources your synthesis is anchored to. Stable, authoritative, and verifiable. Goes into _refs/<snapshot>.md (for cacheable content) and/or stable URLs recorded in the inbox file's ground_truth: field.

The synthesis is worthless without ground truth. A later /ziki-inbox pass — possibly days later, in a different session — will re-verify your claims against the ground-truth sources before promoting the draft to a wiki page. If you file a synthesis with no ground truth, the re-verification step has nothing to check against, and the knowledge you captured degrades into unverifiable hearsay.

Capture ground truth NOW, not later. This skill runs inside a live session that has full context: which files were read, which commits were referenced, which docs were fetched, which repo was explored. That context evaporates the moment the session ends. /ziki-inbox can re-fetch external URLs, but it cannot recover "the state of mikluko/yosh at commit abc1234 that the earlier session was looking at". Ground truth that is not captured here is lost permanently.

What counts as ground truth

• Source code read during the session: snapshot the relevant files (README, key source files, config schemas, Helm values). Record the repo URL pinned to a commit SHA (https://github.com/owner/repo/tree/<sha>) — never bare main.
• External documentation consulted: official docs, RFCs, specifications, vendor guides. Cache substantial pages to _refs/.
• URLs quoted or paraphrased in the conversation: fetch and cache them.
• Transcripts, papers, articles: cache the clean extracted text to _refs/.
• Code artifacts produced by the user in-session (design docs, ADRs, config files they pasted): snapshot them verbatim into _refs/ with a session: origin marker.

What is NOT ground truth

• Your own reasoning, synthesis, or explanation — that is the draft, not the source.
• Other wiki pages — those are derived too.
• Search-result snippets or chat messages about a topic — fetch the primary source instead.
• Ephemeral pages (login walls, auto-generated dashboards, search results).

When in doubt

Ask: "If a future session had to verify every claim in my draft, what would it need to read?" Capture exactly that. If you cannot name a single ground-truth source for a draft, the draft is too speculative — file it with an explicit ground_truth: [] and a status: unverified marker, or skip it.

CRITICAL: vault access method

You MUST read ~/.claude/ziki.md FIRST, before doing anything else. This file contains the vault repository coordinates (YAML frontmatter) and the exact tools or commands to use for reading and writing vault files (markdown body).

Do NOT write to the local filesystem. The vault is a remote git repository. Even if you see a local checkout of the vault (e.g. ~/Documents/ziki/), do not use it. All reads and writes go through the remote access method described in ~/.claude/ziki.md.

If ~/.claude/ziki.md does not exist, stop and tell the user to run /ziki-setup.

Input sources

Handle any of the following (infer from context, no user input required). Each input implies a different ground-truth capture duty — see the right column.

Input	Synthesis	Ground truth to capture alongside
URL	Extract clean text as the draft body, or summarize it	Cache the page verbatim to _refs/ and record the URL
File path	Summarize or extract key ideas	Snapshot the file contents to _refs/ with a session-origin marker
Topic / conversation excerpt	Synthesize a draft from session context	List every primary source the synthesis leans on and cache each one (see below)
Codebase exploration (you read files from a repo before filing)	Synthesis of architecture, design, behaviour	Repo URL pinned to commit SHA + _refs/ snapshots of the specific files you relied on
Combination	Draft that blends a URL with surrounding analysis	All sources above, combined

For the Topic / conversation excerpt and Codebase exploration cases — the ones where you are writing from memory or derivation rather than a single obvious source — you are personally responsible for reconstructing the ground truth from the session. Before writing the draft, list out:

1. Every file you read (with repo + commit SHA).
2. Every URL you fetched.
3. Every external doc or spec you relied on.
4. Any pasted content from the user.

Then cache each of those to _refs/ and record them in the inbox file's ground_truth: field. Only after that should you write the synthesis.

How to file

1. Read ~/.claude/ziki.md: parse frontmatter for vault coordinates, read body for access instructions.
2. Inventory ground truth first: before writing any synthesis, enumerate every primary source the draft will rely on (files read from a repo with their commit SHA, URLs fetched, docs consulted, pasted content). If the list is empty, the draft is unverifiable — either find sources or skip.
3. Cache each ground-truth source to _refs/ (see "Reference snapshots" below). Do this BEFORE writing the draft, so the draft can reference the cached paths.
4. Determine draft content: fetch URL if needed, read file if needed, or synthesize from conversation now that the ground truth is locked in.
5. Deduplicate: read wiki/_index.md and list _inbox/ directory from the vault (using the remote access method). If a near-duplicate exists, skip silently. Also list _refs/ and reuse any existing snapshot instead of creating a duplicate.
6. Choose filename: <kebab-case-title>.md (short, descriptive, no dates).
7. Prepare the inbox file with this format:

---
title: "<Title>"
type: concept | entity | comparison | synthesis | reference
tags: [tag1, tag2]
sources:
  - <where the synthesis came from: session context, conversation excerpt, a user message, etc.>
ground_truth:
  - _refs/<snapshot>.md
  - https://github.com/owner/repo/tree/<commit-sha>
  - https://docs.example.com/spec  # stable canonical URL
created: YYYY-MM-DD
status: inbox
---

# Title

Content here. Claims that lean on a specific ground-truth source should say so
inline (e.g. "per `_refs/sing-box--vless-inbound.md`" or "per yosh `main.go` at
`abc1234`"), so the `/ziki-inbox` re-verification step can trace each claim to a
source without guessing.

The ground_truth: list is required and must be non-empty for any draft that makes factual claims. An empty list is allowed only for pure opinion, preference, or personal-journal entries — and those should also carry status: unverified.

8. Write files to the vault in a single commit:

   • _inbox/<filename>.md
   • One _refs/<snapshot>.md per ground-truth source you cached
   • Commit message: ziki: add to inbox — <title>

   Prefer a single commit that contains the draft and all of its ground-truth snapshots together. A draft that lands without its refs breaks the verification chain.

Reference snapshots (_refs/)

_refs/ is the ground-truth cache. Every inbox draft that makes factual claims should land with at least one _refs/ snapshot in the same commit. This is not optional sugar — it is the mechanism that makes the re-verification step in /ziki-inbox possible at all.

When to cache: any primary source the draft depends on — web pages, docs, source files from a repo, specifications, transcripts, pasted user content. Do NOT cache trivial pages, search-result SERPs, or auto-generated dashboards.

When NOT to cache (reference the URL only instead): content already available at a stable canonical URL that will not rot (RFCs on rfc-editor.org, W3C specs, pinned git permalinks). In these cases record the stable URL directly in ground_truth: and skip the _refs/ snapshot.

Naming convention:

• Web content: <domain>--<kebab-title>.md (e.g. docs-nats-io--jetstream-overview.md)
• Repo file snapshots: <owner>-<repo>--<path-kebab>@<short-sha>.md (e.g. [email protected])
• User-pasted content: session--<kebab-title>.md (e.g. session--yosh-design-notes.md)

Frontmatter format (adapt to origin):

---
# For web content:
url: "https://docs.nats.io/nats-concepts/jetstream"
fetched: YYYY-MM-DD
content_type: documentation | article | specification | transcript

# For repo file snapshots (in addition to or instead of url):
repo: "mikluko/yosh"
path: "cmd/bot/main.go"
commit: "abc1234"
fetched: YYYY-MM-DD
content_type: source-code

# For session-origin content:
origin: session
captured: YYYY-MM-DD
content_type: design-note | pasted-text | transcript
---

# Page Title or File Path

Extracted content here (clean markdown / verbatim source, no HTML noise).

Rules for _refs/:

• Clean, extracted markdown (or verbatim source code) — never raw HTML
• Include substantive content only; strip navigation, ads, chrome
• One file per source (URL, repo-file-at-commit, or pasted artifact)
• Deduplicate: list _refs/ and reuse an existing snapshot before creating a new one
• For repo files, always pin to a commit SHA — never reference main/HEAD
• When the same topic spans multiple files of a repo, it is fine to create multiple snapshots; keep each one focused on a single file or section

Tags

Read _meta/taxonomy.md from the vault to select tags. Extend the vocabulary there if a new tag is clearly needed.

Rules

• NEVER prompt the user for confirmation or input
• NEVER announce what you are doing unless the user explicitly invoked /ziki-add
• NEVER read or write the local filesystem for vault operations
• NEVER use ~/Documents/ziki/ or any other local path
• NEVER invent sources or citations
• NEVER file a synthesis draft without its ground-truth snapshots in the same commit — the draft is not useful without the sources it was derived from
• ALWAYS inventory ground truth BEFORE writing the synthesis, not after
• ALWAYS pin repo references to a commit SHA, never main/HEAD
• ALWAYS populate the ground_truth: field; the only acceptable empty list is on opinion/preference entries, which must also carry status: unverified
• If content is too thin (stub, one-liner with no substance), skip silently
• If you cannot identify any ground-truth source for a factual draft, skip it — unverifiable synthesis rots the wiki
• One _inbox/ file per distinct concept; do not bundle unrelated things
• Deduplicate: check wiki/_index.md and existing _inbox/ files before creating a near-duplicate; check _refs/ before creating a near-duplicate snapshot