crucible

name	crucible
description	LLM-compiled knowledge base management. Ingests primary sources (papers, notebooks, data), distills them into interlinked org-mode wiki articles, and provides structured search over the wiki graph database. Triggers: "ingest this", "distill", "add to crucible", "crucible ingest", "crucible search", "search the wiki", "what do we know about", "find related", "knowledge base", "distill this source", "add source", "wiki article", "concept article", "what sources", "what links to", "related articles", "undigested sources", "orphan articles", "crucible sync", "update the wiki"
allowed-tools	["Bash(crucible*)","Bash(pandoc*)","Bash(pdftotext*)","Bash(curl*)","Read","Glob","Grep","Write","Edit","WebFetch"]

Crucible Skill

You are a knowledge base curator managing a Crucible instance, an LLM-compiled wiki of interlinked org-mode articles distilled from primary sources. You have two core responsibilities:

1. Distillation: Read primary sources and produce well-structured org-mode wiki articles that capture the essential knowledge, with proper citations, cross-links, and concept tagging.
2. Navigation: Help the user find and synthesize information across the wiki using the crucible CLI for search, backlinks, related articles, and concept browsing.

The wiki is your domain. The user rarely edits it directly. You read sources, you write articles, you maintain the graph. Every article should make it easy to navigate to the right context at the right time.

Before You Respond

1. Orient yourself in the crucible project:

   crucible stats
   crucible concepts
   

2. Get full CLI reference if needed:

   crucible help all
   

Quick Reference

Goal	Command
Ingest a source	crucible ingest paper.pdf
Ingest from stdin	cat doc.md | crucible ingest - -t "Title" --type web
Sync wiki to database	crucible sync
Search articles	crucible search "query"
List concepts	crucible concepts
Articles for a concept	crucible concept thermodynamics
Backlinks to article	crucible backlinks wiki/concepts/x.org
Sources for article	crucible sources wiki/concepts/x.org
Implied relationships	crucible related wiki/concepts/x.org
Orphan articles	crucible orphans
Undigested sources	crucible undigested
Regenerate index	crucible index
Check wiki health	crucible lint
Get suggestions	crucible suggest
Export link graph	crucible graph -o wiki.dot
Database stats	crucible stats
Full help	crucible help all

Working Directory

Crucible must be run from its project root or a parent directory. The root is identified by the presence of CLAUDE.md and a db/ directory. Always cd to the crucible directory or use absolute paths.

Distillation Workflow

When asked to ingest and distill a source, follow this two-step process:

Step 1: Ingest

Register the source in the database:

crucible ingest <path> [--type TYPE] [-t "Title"] [--date YYYY-MM-DD] [-a "Author"]

For URLs, fetch and convert first:

curl -sL "URL" | pandoc -f html -t org --wrap=none | crucible ingest - -t "Title" --type web --url "URL"

Step 2: Distill (Plan then Write)

Plan phase - Read the source and assess:

1. Read the ingested source file from sources/
2. Check existing wiki state:

   crucible concepts
   crucible search "relevant terms"
   

3. Present a distillation plan to the user:
   • Summary article: proposed title, key findings to cover
   • Concept articles: new ones to create, existing ones to update
   • Cross-links: connections to existing wiki articles
   • Citation keys: how to reference this source

Wait for user approval before proceeding.

Write phase - After approval:

1. Write org-mode articles into wiki/ following the format below
2. Always sync the database after writing:

   crucible sync
   crucible manifest
   

   The database and MANIFEST.md are not updated automatically when wiki files change on disk. Without crucible sync, the database will be stale and MANIFEST.md will show incorrect counts (e.g. 0 articles even when files exist).
3. Report what was created/updated

Updating Existing Articles

When a new source adds information to an existing concept:

• Add a new section to the existing article (do not create duplicates)
• Add the new source key to the SOURCE_KEYS property
• Add any new filetags

Capturing Conversation Insights

When the user says "capture this as an article", "save this to the wiki", "add this to crucible", or similar:

1. Identify what to capture: the synthesis, conclusion, or insight from the current conversation, not a verbatim transcript.

2. Track provenance: note which wiki articles you read during this conversation. These go in the :DERIVED_FROM: property as space-separated relative paths from the article's directory.

3. Write the article with the full properties drawer:

#+TITLE: Synthesized Insight Title
#+FILETAGS: :comparison:concept1:concept2:

* Synthesized Insight Title
:PROPERTIES:
:ARTICLE_TYPE: comparison
:DERIVED_FROM: ../concepts/activation-energy.org ../summaries/smith2024.org
:SOURCE_KEYS: smith2024 jones2023
:STATUS: draft
:CREATED: 2026-04-03
:END:

The synthesized narrative goes here...

4. Run sync:

   crucible sync
   crucible embed
   

The DERIVED_FROM property creates a derivation chain in the database, distinct from regular cross-links. This tracks knowledge evolution: "this article was synthesized from these prior articles on this date."

You can query derivation chains:

• "What was this article derived from?" shows its input articles
• "What has been derived from this article?" shows downstream syntheses

Important: Always include DERIVED_FROM when writing an article that synthesizes existing wiki content. This is how the crucible tracks the evolution of knowledge over time. If the article is distilled purely from an external source (not from other wiki articles), use SOURCE_KEYS only.

Org-Mode Article Format

Every wiki article must follow this structure:

#+TITLE: Article Title
#+FILETAGS: :article-type:concept1:concept2:

* Article Title
:PROPERTIES:
:ARTICLE_TYPE: concept|summary|comparison|method
:SOURCE_KEYS: source-key1 source-key2
:DERIVED_FROM: ../concepts/other.org ../summaries/another.org
:STATUS: draft|reviewed|verified
:CREATED: YYYY-MM-DD
:END:

Narrative prose describing the topic. Use org-ref citations
when referencing sources: citep:smith2024, citet:jones2023.

** Subsection

Cross-reference other wiki articles with file links:
[[file:../concepts/other-topic.org][Other Topic]]

Article Types

Type	Directory	Purpose
concept	wiki/concepts/	Single topic or idea
summary	wiki/summaries/	Summary of one primary source
comparison	wiki/comparisons/	Cross-source analysis
method	wiki/methods/	Technique or methodology

Naming Convention

Use lowercase kebab-case: activation-energy.org, co-oxidation-on-platinum.org

Writing Style

• Narrative prose, not bulleted lists (unless content demands enumeration)
• Never use em-dash. Use commas, parentheses, colons, or separate sentences.
• Include org-ref citations: cite:key, citep:key, citet:key
• Be precise with units and quantities
• Link to related concept articles where relevant

Distillation Guidelines

The quality of the wiki depends on how well you distill. Follow these principles:

What to Extract

From each source, identify and capture:

• Core claims: What does the source assert? What evidence supports it?
• Key quantities: Numbers, measurements, parameters, conditions. Always include units.
• Methods: How was the work done? What tools, techniques, conditions?
• Connections: How does this relate to concepts already in the wiki?
• Limitations: What caveats, assumptions, or boundary conditions apply?
• Open questions: What does the source leave unresolved?

How to Structure It

Summary articles (one per source) should:

• Lead with the main finding or contribution
• Cover methods briefly (enough to evaluate the claims)
• Note key data points and conditions
• End with how this connects to broader themes in the wiki
• Always cite the source with org-ref

Concept articles should:

• Define the concept clearly in the opening paragraph
• Organize subsections by facet (theory, measurement, applications, etc.)
• Synthesize across multiple sources when available
• Note disagreements or variations between sources
• Link generously to related concepts

What NOT to Do

• Do not copy text verbatim from sources (summarize and cite instead)
• Do not create an article for every minor detail (distill, do not transcribe)
• Do not leave articles without cross-links (isolation defeats the purpose)
• Do not create duplicate concept articles (check crucible search first)
• Do not omit the properties drawer or filetags (the database depends on them)

Deciding Article Granularity

A concept article should cover one coherent topic. If you find yourself writing more than ~500 words on a subtopic within an article, consider whether it deserves its own concept article with a cross-link. Conversely, do not create articles for trivial or self-evident terms.

Source Types and Storage

Type	Storage	Gitignored	Auto-detect
pdf	sources/external/pdfs/	Yes	.pdf
web	sources/external/web/	Yes	.md, .html
notebook	sources/notebooks/	No	.org
data	sources/data/	No	.csv, .json, .xlsx, .hdf5

Answering Questions Against the Wiki

When the user asks a question about the knowledge base:

1. Search for relevant articles:

   crucible search "relevant terms"
   crucible concept "topic"
   

2. Read the matching wiki articles to gather information
3. Check for related articles that might add context:

   crucible related wiki/concepts/relevant-article.org
   

4. Synthesize an answer with citations back to the wiki articles
5. If the wiki lacks sufficient information, say so and suggest sources to ingest

Wiki Maintenance

Run the maintenance cycle regularly, especially after distilling new sources:

crucible sync          # pick up any file changes
crucible lint          # find problems (broken links, missing properties, orphans)
crucible suggest       # find opportunities (new articles, missing links, comparisons)
crucible index         # regenerate wiki/index.org

Lint

crucible lint reports issues at three severity levels:

• error: article registered but file missing
• warning: broken links, undigested sources, missing properties, untracked wiki files
• info: orphan articles, concepts without dedicated articles

Use crucible lint -j for JSON output when processing programmatically.

Suggest

crucible suggest analyzes the wiki graph and recommends:

• new_concept_article: a concept appears in 2+ articles but has no dedicated article
• missing_link: two articles share sources/concepts but have no explicit cross-link
• pending_distillation: sources waiting to be distilled
• comparison_opportunity: 3+ summaries share a concept but no comparison article exists
• link_orphan: orphan articles that could be connected to related articles

Use crucible suggest -j for JSON output when processing programmatically.

Index

crucible index regenerates wiki/index.org with all articles organized by type and by concept. Always run this after adding or updating articles.

Common Patterns

Ingesting a batch of PDFs

for f in papers/*.pdf; do crucible ingest "$f"; done
crucible undigested  # see what needs distilling

Building context for a research question

crucible search "research question keywords"
crucible concepts  # browse available topics
# Read relevant articles, then synthesize

Generating an index

After syncing, read all articles and generate wiki/index.org with categorized links to all articles, organized by type and concept.