.wiki-schema.md

.wiki-schema.md

This file defines the authoritative schema for WEIPING_WIKI / Weiping Wiki.

Historical aliases preserved for compatibility: vipin wiki, vipinknowledge, and vipin-wiki. Schema, navigation, and new documentation should use WEIPING_WIKI / Weiping Wiki unless they are explicitly describing old paths, old prompts, or legacy automation.

It exists to make the repository operate like a durable knowledge system rather than a loose note folder.

System Goal

Compile raw sources into a maintained wiki that supports:

• incremental ingest
• durable synthesis
• query-time retrieval from curated pages rather than raw rediscovery
• explicit uncertainty handling
• safe separation between public and private knowledge
• reader-specific interpretation and prioritization

Core Layers

1. Raw layer

raw/ stores source-of-truth materials and source pointers.

Rules:

• treat raw/ as immutable during normal ingest
• store public-safe research and learning materials in normal raw/ subfolders
• store sensitive materials only in raw/private-*

2. Public wiki layer

wiki/ stores publishable or semi-public knowledge pages.

This is the default query surface and the default layer used for GitHub publication.

3. Private wiki layer

wiki-private/ stores local-only knowledge records for sensitive materials.

Rules:

• never reference wiki-private/ from files that are intended to stay public
• never add wiki-private/ to public indexes or logs
• use minimal metadata when storing intimate or high-sensitivity materials

4. Schema and operating layer

The operating layer is defined by:

• AGENTS.md
• .wiki-schema.md
• purpose.md
• reader-context.md
• CONTRIBUTIONS.md
• WORKFLOWS.md
• scripts/

Directory Taxonomy

Public

• wiki/home.md
• wiki/index.md
• wiki/log.md
• wiki/overview.md
• wiki/entities/
• wiki/concepts/
• wiki/topics/
• wiki/sources/
• wiki/analyses/
• wiki/comparisons/
• wiki/queries/
• wiki/synthesis/
• wiki/synthesis/sessions/
• wiki/timelines/
• wiki/_templates/

Private

• wiki-private/log.md
• wiki-private/sources/

Knowledge Object Types

Every durable page should declare a type in frontmatter.

Canonical types:

• overview
• index
• log
• entity
• concept
• topic
• source
• analysis
• comparison
• query
• synthesis
• timeline
• catalog

Confidence Taxonomy

When pages contain non-trivial claims, prefer recording claim status with one of:

• EXTRACTED: directly supported by source material
• INFERRED: reasoned synthesis from multiple signals
• AMBIGUOUS: present but unclear, incomplete, or contested
• UNVERIFIED: plausible but not yet checked carefully

Recommended usage:

• source notes should lean heavily on EXTRACTED
• comparison and synthesis pages may contain INFERRED
• unresolved tensions should be marked AMBIGUOUS
• provisional notes should be marked UNVERIFIED

Optional lifecycle fields (LLM Wiki v2)

Pages may additionally carry optional, machine-readable lifecycle metadata consumed by python scripts/wiki.py lifecycle:

• confidence: numeric 0–1 (or a taxonomy label) for page-level confidence
• last_confirmed: ISO date the page's claims were last re-verified (a reinforcement signal)
• source_count: integer count of supporting sources
• superseded_by: wiki id of the page that supersedes this one

These fields are optional; pages omitting them are handled gracefully. Retention is modeled with an Ebbinghaus decay curve whose half-life varies by page type and resets on reinforcement (a newer updated / last_confirmed).

Query Surface

Unless the user explicitly asks for private material, the default query surface is:

1. wiki/index.md
2. relevant pages in wiki/
3. optional source files in raw/

Private materials are opt-in.

Workflow Vocabulary

The knowledge base recognizes these operational modes:

• init
• ingest
• batch-ingest
• query
• search
• context
• digest
• lint
• status
• graph
• delete
• maintain
• crystallize
• lifecycle
• scrub

init

Create or repair the repository structure, schema files, templates, and key indexes.

ingest

Read one source, create or update source notes, then propagate changes into concept, entity, and synthesis pages.

batch-ingest

Treat a folder or collection as a source set. First build a collection note, then decide whether to create per-item notes immediately or later.

query

Answer questions from the maintained wiki first. If the result is durable, save it under wiki/queries/ or wiki/analyses/. Default to preserving reusable or operationally important Q&A instead of leaving it only in chat.

search

Search the machine-readable wiki catalog when index-only lookup stops scaling.

context

Assemble layered L0/L1/L2/L3 context packs for future sessions and long-running tasks.

digest

Produce a higher-order synthesis, comparison, report, or timeline from multiple pages.

lint

Check for:

• broken wiki links
• orphan pages
• pages absent from the index
• stale or weakly sourced claims
• private/public boundary leaks

status

Summarize current repository health and scale.

graph

Generate a wiki-link graph from the public wiki.

delete

When removing public content, also clean index and log references. Private deletions must not leave public traces. Actual deletion of information requires explicit user approval after a concrete deletion proposal.

maintain

Run periodic CRUD maintenance across the maintained wiki. Create missing homes, update stale or weak pages, merge duplicates, preserve useful old information, and prepare deletion proposals for garbage pages whose continued presence lowers retrieval quality, accuracy, safety, or usability.

crystallize

Turn a high-value conversation result into a durable page.

lifecycle

Advisory audit of memory lifecycle: numeric confidence, Ebbinghaus retention decay, and supersession candidates. Report-first and human-gated; --apply only stamps optional date fields onto pages that lack them.

scrub

Scan a source file for secrets and private paths before it becomes a page. Report-first; --apply writes a redacted copy and never overwrites the original.

Workflow Routing Rules

Use the following routing rules when deciding where work should land.

• init updates repository scaffolding, core docs, templates, cache helpers, and section entry pages.
• ingest creates or updates one source note and then propagates durable changes to entities, concepts, topics, comparisons, or synthesis pages.
• batch-ingest first creates a collection note and research map before deciding whether each member needs its own source note.
• query starts from wiki/index.md, then drills into the smallest relevant set of maintained pages.
• query should usually produce both an answer and a durable wiki update when the exchange teaches the system something reusable.
• search uses wiki/catalog.json plus scored retrieval from maintained pages.
• context packages just enough state for the next task instead of loading the full wiki.
• digest writes multi-page syntheses, comparisons, timelines, or topic maps.
• lint checks public pages only and must also verify that private paths do not leak into public notes.
• status summarizes scale, freshness, and recent activity across both public and private layers without exposing private details.
• graph operates only on wiki/ and must ignore wiki-private/ and raw/private-*.
• delete requires explicit user approval, then removes references from index, graph, and durable section homes before deleting a page.
• maintain performs evidence-disciplined CRUD cleanup, preserves useful old information, and should not be biased toward accumulation of garbage.
• crystallize promotes durable chat results into wiki/queries/, wiki/analyses/, wiki/comparisons/, wiki/timelines/, or wiki/synthesis/sessions/.

Section Roles

• wiki/overview.md describes the current shape of the knowledge base and major active domains.
• wiki/topics/ stores durable subject clusters that are broader than a single concept and more stable than a one-off analysis.
• wiki/comparisons/ stores structured side-by-side evaluations, tradeoff tables, and alternatives.
• wiki/synthesis/ stores ongoing long-horizon synthesis pages.
• wiki/synthesis/sessions/ stores dated synthesis increments or crystallized working memos.

Q&A Routing Rule

When a conversation produces durable value, prefer updating the existing knowledge structure rather than creating isolated notes by default.

Use:

• wiki/queries/ for direct answers likely to be reused
• wiki/analyses/ for synthesis-heavy answers
• wiki/comparisons/ for evaluative or tradeoff answers
• wiki/concepts/ or wiki/topics/ when the exchange improves a stable subject page

Reader Layer

reader-context.md is a first-class input to interpretation.

Use it when:

• deciding emphasis
• ranking what matters
• choosing what should become durable
• shaping comparisons or recommendations

Do not use it as a license to distort source facts.

Relation Vocabulary

Default wiki links can stay unlabeled, but when relation labels help, prefer:

• supports
• contradicts
• compares
• extends
• depends-on
• derived-from
• supersedes
• superseded-by

A relation label written immediately before a wiki link (e.g. supersedes [[old-page]]) is parsed into the catalog's typed_links and is queryable via python scripts/wiki.py graph.

Public / Private Safety Rules

• no direct public references to specific files under raw/private-*
• no public index entries describing private image or video sets
• no private details copied into wiki/log.md
• no private pages staged for Git
• no fake certainty added just to complete an argument

Filesystem Scope Safety Rule

• broader local tool permissions do not remove the need for user intent
• the default edit scope is the current project or explicitly named repository
• files outside that scope require either:
  • an explicit user request, or
  • a confirmation step before editing
• use wide local access to unblock requested work, not to opportunistically edit unrelated areas

Naming Rules

• stable topics use plain kebab-case names
• dated transient notes use YYYY-MM-DD-title
• collection notes use stable collection-oriented names when the collection is durable

Maintenance Expectations

• keep wiki/index.md human-readable
• keep wiki/catalog.json machine-readable
• keep wiki/log.md append-only
• prefer editing existing pages over creating duplicates
• split pages once they become too broad to maintain cleanly
• keep section home pages updated when a new durable page type is introduced
• when a page addresses a contested topic, include ## Counterpoints and Gaps