DocTology

English | 한국어

DocTology is an Obsidian-first LLM Wiki runtime and reusable skill pack.

The core contract is intentionally simple:

• the human curates sources and asks questions
• the agent maintains the wiki
• scripts preserve source identity, indexes, and provenance
• ontology and graph layers are optional support surfaces, not the product face

DocTology is for building a knowledge system where an LLM can read a durable wiki, follow links, inspect source-backed evidence, and keep improving the knowledge base over time.

What this is

DocTology is not just a notes repo, not just an ontology toolkit, and not just a graph experiment.

It is a way to build a repository where:

• raw/ stores immutable source material
• warehouse/jsonl/ stores canonical structured truth when ontology-backed ingest is useful
• wiki/ stores human-readable synthesis that agents maintain with Obsidian links
• AGENTS.md is the repo-local operating contract for future agents
• intelligence/ YAML is a thin contract/hint layer below AGENTS, wiki, and source evidence

The wiki is the primary reading and reasoning surface. YAML is not a second wiki and should not contain semantic conclusions.

Who this is for

Use DocTology if you want:

• a readable knowledge base, not just a vector index or raw context dump
• an LLM-maintained wiki that can grow from repeated source ingest and questions
• stronger provenance than plain notes, without forcing heavy ontology or graph infrastructure on day one
• reusable skills for bootstrapping, ingesting, ontology maintenance, and operator workflows

DocTology workbench question workspace — an optional read-and-review surface for the generated wiki, previews, and source/graph hints.

Workbench status: it is an optional review surface, not the source of truth or the primary LLM reasoning layer. Durable synthesis belongs in the wiki under the repo-local AGENTS.md contract.

Reference example — previously separate Obsidian notes forming visible structure, links, and neighborhoods.

Default path

If you are unsure where to start, use the default DocTology path:

1. bootstrap a wiki-first workspace
2. put sources into raw/inbox/
3. ingest sources into source pages, citation anchors, and optional ontology JSONL
4. let the agent maintain the wiki under AGENTS.md
5. save durable answers into wiki/analyses/
6. add ontology, graph, or operator workflows only when provenance, contradiction handling, or repeated maintenance needs them

That default path is the product promise:

• readable wiki first
• source-backed evidence second
• ontology-backed verification when useful
• graph/operator complexity only when it earns its keep

Which path am I on?

Use this practical chooser:

• Want to create a new wiki?
  • Use llm-wiki-bootstrap
• Want to ingest new material?
  • Use llm-wiki-ontology-ingest
• Want to inspect claims, evidence, or entities?
  • Use lightweight-ontology-core
• Want graph neighborhoods, paths, or relation exploration?
  • Use lg-ontology
• Want to organize codebase docs and AGENTS memory?
  • Use repo-docs-intelligence-bootstrap
• Want to refresh or validate existing ontology/wiki outputs?
  • Use ontology-pipeline-operator

Most users should begin with:

1. llm-wiki-bootstrap
2. repeated llm-wiki-ontology-ingest

Treat the other skills as later-stage refinement or optional extension layers.

If you are already operating a DocTology repo

1. Read AGENTS.md first.
2. Put new sources into raw/inbox/.
3. Run python scripts/llm_full_ingest.py raw/inbox/source.md --apply when configured helper LLM ingest is available.
4. Use llm-wiki-ontology-ingest or direct agent-maintained ingest when the source needs extra review or repair.
5. Review git diff, then run lint/status checks.
6. Use ontology-pipeline-operator when existing outputs need refresh or validation.

scripts/llm_wiki.py ingest is registration only. scripts/llm_full_ingest.py --apply is the minimal configured-LLM growth loop: raw -> register -> source page -> affected wiki pages -> proposed JSONL -> meta refresh -> ingest report. Automatic apply must not modify raw/, create accepted truth, delete content, rename pages, merge pages, or auto-commit.

For automated graph ingest, use scripts/wiki_growth_graph.py. That runtime requires real LangGraph and a configured ingest LLM, and fails fast instead of falling back to deterministic semantic shortcuts. The agent-operated wiki workflow remains available outside that strict graph runtime.

Choose your starting path first

1) Do you want to start with an LLM Wiki?

Start with llm-wiki-bootstrap.

The flow is simple:

• run the wiki bootstrap
• put documents into the generated raw/inbox/
• run llm-wiki-ontology-ingest when you want source pages plus ontology-backed provenance
• ask the agent to answer from the wiki map first, then relevant page bodies and source citations
• let durable answers update wiki/analyses/ and, when appropriate, affected concept/entity/person/project pages

The first step is always wiki-first.

2) Do you want stronger ontology structure under the wiki?

Use lightweight-ontology-core.

This stage is for:

• entities
• claims
• evidence links
• segments
• relation vocabularies
• contradiction or supersession handling

The ontology layer should support the wiki. It should not replace the wiki as the human-facing reasoning surface.

3) Do you want graph-style neighborhood exploration?

Use lg-ontology.

This stage is optional. It helps with graph projection, multi-hop inspection, and neighborhood/path exploration, while keeping canonical truth in JSONL.

Do not treat graph projection as canonical truth.

4) Do you want project-specific repo memory instead of a personal LLM Wiki?

Use repo-docs-intelligence-bootstrap.

This is better for:

• capturing the current state of a codebase
• creating repo-local project memory for agents
• aligning docs, AGENTS, manifests, and lightweight intelligence contracts

This is an alternative starting bootstrap, not something to blindly stack on top of the wiki bootstrap.

Caution

Use only one bootstrap to start.

Multiple bootstraps can overwrite AGENTS.md and blur the operating rules.

Choose first:

• do you want to grow an LLM Wiki?
• or do you want repo-focused intelligence / project memory?

Both matter, but the first bootstrap should be one clear choice.

Core skill paths

The canonical repo-local skillset lives under .agents/skills/. Installed copies under ~/.codex/skills are local installs only.

• .agents/skills/llm-wiki-bootstrap
  • start an Obsidian-first LLM Wiki
• .agents/skills/llm-wiki-ontology-ingest
  • ingest inbox documents into an ontology-backed wiki
• .agents/skills/lightweight-ontology-core
  • refine canonical ontology truth beneath the wiki
• .agents/skills/lg-ontology
  • extend into ontology graph / neighborhood exploration
• .agents/skills/repo-docs-intelligence-bootstrap
  • bootstrap project-specific memory / repo intelligence
• .agents/skills/ontology-pipeline-operator
  • refresh existing ontology/wiki artifacts and repeated maintenance flows

Operating model

The DocTology core model is intentionally small:

raw source
  ↓
source page and optional ontology JSONL
  ↓
LLM-maintained wiki pages
  ↓
saved analyses and cross-links
  ↓
better future answers

Responsibilities:

• deterministic scripts may register sources, keep IDs stable, refresh indexes, and validate basic structure
• the LLM agent performs semantic synthesis by reading the wiki, source pages, and relevant ontology evidence
• humans review broad rewrites, sensitive accepted claims, contradictions, and major ontology changes
• the pipeline closes artifact coverage, not semantic judgment

This keeps the system close to a Karpathy-style LLM Wiki: the LLM reads a structured, linked knowledge base instead of receiving only top-k chunks.

YAML contract layer

YAML is useful, but it is subordinate.

There are two separate priority axes.

Truth / provenance priority:

1. raw/ source material
2. warehouse/jsonl/ canonical structured truth when ontology-backed ingest exists
3. source-backed wiki pages and citations
4. derived graph/retrieval/workbench previews

Operating guidance priority:

1. repo-local AGENTS.md
2. wiki/_meta/index.md and recent wiki/_meta/log.md
3. intelligence/ YAML contracts and hints

YAML may define vocabulary, dataset boundaries, profiles, and validation hints. It must not become a second semantic wiki or a deterministic reasoning engine.

Helper LLMs

wikiconfig.json is a local-only configuration file. Use wikiconfig.example.json as the committed template.

Helper LLMs are optional accelerators for bounded tasks. If helper LLMs are disabled or absent, the surrounding chat agent can still perform semantic work directly by reading:

• AGENTS.md
• wiki/_meta/index.md
• relevant wiki pages
• source pages
• warehouse/jsonl/ evidence when needed

In other words, helper LLMs should not replace the main agent-maintained wiki loop.

Semantic no-fallback principle: if the helper/configured LLM call fails, report the step as failed, partial, or pending. Do not replace it with deterministic fallback prose and call full ingest complete.

Probe local helper configuration before using it:

python scripts/helper_llm.py --root . --check-config
python scripts/helper_llm.py --root . --probe-chat
python scripts/helper_llm.py --root . --probe-embedding

For the simplest full growth loop, keep scripts/llm_wiki.py ingest as registration-only and use:

python scripts/llm_full_ingest.py raw/inbox/example.md --mode dry_run
python scripts/llm_full_ingest.py raw/inbox/example.md --apply
python scripts/wiki_growth_graph.py check --source raw/inbox/example.md

The strict LangGraph source-page runtime remains available for graph-runtime debugging:

python scripts/wiki_growth_graph.py ingest raw/inbox/example.md --mode draft
python scripts/wiki_growth_graph.py ingest raw/inbox/example.md --mode apply-source-page

--apply completes source pages, creates or appends affected wiki pages, writes proposed JSONL records, refreshes index/log, and writes an ingest report. Accepted-claim promotion remains intentionally review-gated.

When a later question requires raw/source fallback or wiki repair, record the trace without adding semantic heuristics:

python scripts/llm_wiki.py answer-receipt "Question text" \
  --used-wiki wiki/_meta/index.md \
  --used-raw raw/inbox/example.md \
  --wiki-update wiki/analyses/example.md

Answer receipts are context receipts, not answer generators or page-selection rules. The agent still decides what to read and what the answer means.

About the reference runtime

The included local runtime is a reference implementation, not the whole product.

Useful entry points include:

• scripts/llm_wiki.py for source registration, answer receipts, indexing, linting, and status checks
• scripts/helper_llm.py for local wikiconfig.json probes and OpenAI-compatible helper calls
• scripts/wiki_growth_graph.py for strict LangGraph source-page growth runtime
• scripts/pipeline_check.py for pending-aware structural route checks
• scripts/llm_full_ingest.py for configured-LLM full growth dry-run/apply
• scripts/incremental_ingest.py for repeated export-style ingest paths
• scripts/workbench_api.py as a compatibility shell for local workbench adapters
• apps/workbench/ as an optional GUI/read-review surface

The main point of this repository is the operating pattern:

build a readable source-backed wiki, let agents maintain it, and add ontology or graph machinery only when it improves provenance and reasoning quality.

Appendix: Skill invocation rule

Skills are support tools. The center of DocTology remains:

• AGENTS.md
• wiki/
• raw/
• warehouse/jsonl/

When using a skill, keep the repo-local contract explicit:

Use <skill-name>.
Follow the repo-local AGENTS.md.
Do not replace the wiki with YAML or graph outputs.
Keep wiki/ as the human-facing synthesis surface.

Example:

Use llm-wiki-ontology-ingest.
Follow the repo-local AGENTS.md.
Process sources from raw/inbox.
Update source pages, affected concept/project pages, and JSONL provenance when useful.
Refresh wiki/_meta/index.md and wiki/_meta/log.md.