nanobot-runtime/cml/wiki/SCHEMA.md

Wiki Schema

This file is the configuration for this wiki. It documents the conventions, page types, tag taxonomy, and any workflow customizations. The LLM reads this first when entering the wiki, and its conventions override the defaults documented in the llm-wiki skill.

This file is co-evolved with the user. When the LLM notices a recurring pattern in your edits or feedback that isn't here, it will propose adding it. When something here stops fitting, prune it.

Wiki location

• Wiki root: wiki/
• Raw sources: raw/
• Asset/image storage: raw/assets/

Page types

This wiki uses these page types, each with a dedicated subdirectory:

• source (in wiki/sources/) — one summary page per ingested source.
• entity (in wiki/entities/) — pages about specific things: people, papers, products, places, organizations.
• concept (in wiki/concepts/) — pages about ideas, methods, frameworks, abstractions.
• synthesis (in wiki/synthesis/) — cross-cutting analyses, comparisons, query answers filed back.

Add additional types here as the wiki evolves.

Tag taxonomy

(Empty initially. Add tags here as you adopt them, with one-line descriptions. Keep this list small and disciplined — a wiki with 200 tags has effectively no tags.)

Example structure:

• methodology — pages about research or analytical methods.
• open-question — pages or sections that flag unresolved questions.
• contested — pages where sources contradict.

Page sizing

• Soft cap: 400 lines / ~2,000 words. Consider splitting beyond this.
• Hard cap: 800 lines. Must split.

Frontmatter requirements

Every page must have:

• type
• title
• tags
• created
• updated

Plus type-specific:

• source pages: authors, url (if applicable), raw, ingested
• Non-source pages: sources listing the source-summary pages drawn from

Optional graph metadata

Pages may declare typed graph metadata under a top-level graph: key. This is the source of truth for the compiled knowledge graph under wiki/graph/. Markdown remains canonical; the graph is a regenerable index. Pages without graph: still appear as nodes (derived from type/kind) and still contribute mentions edges from body [[wikilinks]].

graph:
  node_id: person:praney-behl       # optional; default <node_type>:<slug>
  node_type: person                  # optional; default mapped from type/kind via ontology
  canonical: true                    # mark as canonical when multiple slugs alias the same entity
  aliases: [Praney, praney@example.com]
  relationships:
    - predicate: founded
      object: company:seedblocks
      source: praney-founder-context-dump   # source-page slug
      evidence: "Solo technical founder and sole director..."
      confidence: high               # high | medium | low
      status: current                # current | historical | proposed | disputed | superseded
      # optional:
      # valid_from: 2025-01-15
      # valid_to: 2026-03-01
      # notes: "..."
      # raw_ref: "raw/founder-dump.md#L42"
      # contradicts: edge-id-or-source-slug
      # supersedes: edge-id-or-source-slug

Required fields on every relationship: predicate, object, source, evidence, confidence, status. Predicates and the subject/object types they accept are declared in wiki/graph/ontology.yaml. Typed semantic edges must be supported by an explicit source — never emit one inferred from training data alone.

Index structure

(Update this section when sharding.)

Currently flat: a single wiki/index.md listing all pages.

When the wiki passes ~150 pages or index.md exceeds 300 lines, shard into wiki/indexes/<type>.md and update this section.

Graph layer

The wiki has an optional compiled graph layer under wiki/graph/:

• wiki/graph/ontology.yaml — declares node types and predicates. Tracked. Edit this when you introduce new predicates or domain types.
• wiki/graph/nodes.jsonl, wiki/graph/edges.jsonl — generated. Track in git only if you want graph diffs in PRs.
• wiki/graph/graph.sqlite — generated. Gitignored by default.
• wiki/graph/graph.graphml — generated. Track only if you want to diff it.

Generation is reproducible from markdown via scripts/wiki_graph_extract.py. The graph can be deleted at any time and rebuilt without losing knowledge — markdown is canonical.

Workflow customizations

Paywalled sources

Sites like medium.com (member-only stories) often return only a preview when fetched. When a source is paywalled:

1. Capture what's available. Fetch the URL, extract whatever preview/abstract is accessible, and write it into cml/raw/<slug>.md with a 🔒 paywall marker and the original URL.
2. Never fabricate. Do not infer or hallucinate content behind the paywall. If only the title and first paragraph came through, that's all the source page gets.
3. Flag in source page frontmatter. Add paywall: true to the frontmatter of the corresponding wiki/sources/<slug>.md page so future queries know the coverage is partial.
4. Compile normally. A paywalled source still gets a source-summary page — just with limited content. The wiki should reflect what we actually have, not what we wish we had.
5. Known paywall domains (non-exhaustive): medium.com, substack.com (paid posts), ft.com, wsj.com, nytimes.com (soft paywall), bloomberg.com. When fetching from these, expect partial content and handle accordingly.

User preferences

(Empty initially. As the user expresses style preferences — "always include a 'Why this matters' section on concept pages", "never use bullet lists in summaries", "prefer comparative tables for synthesis pages" — capture them here so they persist across sessions.)

Lint cadence

• Structural lint: after every 5 ingests.
• Semantic lint: weekly or after every 20 ingests.
• Gap-finding: monthly.
• Graph lint + extract: after every ingest that adds typed graph.relationships.

Adjust based on the wiki's growth rate.