abhisekjha/pith/pith-wiki

Wiki mode behavior

When wiki mode is active:

• After significant decisions: offer to save to wiki
• After bugs solved: offer to save resolution
• After architecture discussions: offer to save as decision record
• After ingest: show what was updated, ask for confirmation
• Keep all offers brief: one line. User says yes/no.

Page formats

Entity page (person, company, tool, service, component)

# [Entity Name]
 
**Type:** person | org | tool | service | component
**Summary:** [2 sentences max]
 
## Key Facts
-[fact]
-[fact]
 
## Connections
-[[related-entity]] — [how they relate]
 
## Sources
-[source title](../raw/sources/file.md) — [date]
 
## Contradictions
-[claim in source A] vs [claim in source B] — unresolved

Concept page (idea, pattern, method, principle)

# [Concept Name]
 
**Definition:** [one sentence]
**Why it matters:** [one sentence]
 
## How it works
[2-4 sentences max]
 
## Related
-[[concept]] — [relation]
 
## Examples
-[concrete example]
 
## Open questions
-[what's still unclear]
 
## Sources
-[source](../raw/sources/file.md)

Decision record

# Decision: [what was decided]
 
**Date:** YYYY-MM-DD
**Status:** decided | revisiting | superseded
 
## Context
[1-2 sentences: why this decision was needed]
 
## Options considered
| Option | Pro | Con |
|--------|-----|-----|
| A | ... | ... |
 
## Decision
[what was chosen and single-sentence why]
 
## Consequences
-[what this enables]
-[what this constrains]

Synthesis / analysis page

# [Title]
 
**Thesis:** [one-sentence claim]
**Confidence:** high | medium | low
 
## Evidence
-[point] — [source](../raw/sources/file.md)
 
## Counter-evidence
-[point that argues against the thesis]
 
## Open questions
-[what would change this conclusion]

index.md format

One entry per wiki page. Updated on every ingest or new page.

# Wiki Index
 
## Entities
-[[EntityName]] — [one-line description] — [source count] sources
 
## Concepts
-[[ConceptName]] — [one-line description]
 
## Decisions
-[[Decision-title]] — [date] — [status]
 
## Syntheses
-[[Synthesis-title]] — [one-line thesis]
 
## Sources processed
-[Source Title](raw/sources/file.md) — [date ingested] — [pages updated]

log.md format

Append-only. One entry per operation.

## [YYYY-MM-DD] ingest | [Source Title]
Pages updated: [[page1]], [[page2]], [[page3]]
New pages: [[new-page]]
Contradictions found: [yes/no — detail if yes]
 
## [YYYY-MM-DD] query | [question summary]
Pages consulted: [[page1]], [[page2]]
Answer filed: [[synthesis-page]] (yes/no)
 
## [YYYY-MM-DD] lint
Issues found: [N orphan pages, M stale claims, K missing cross-refs]

Ingest workflow

When /pith ingest <file> is called:

1. Run python3 tools/ingest.py <file>

When /pith ingest --url <url> is called:

1. Run python3 tools/ingest.py --url <url>

• Fetches URL, strips HTML, saves to raw/sources/YYYY-MM-DD-slug.md
• Then runs same ingest pipeline as a local file

Compile workflow

When /pith compile is called:

1. Run python3 tools/compile.py

• Reads all files in raw/sources/
• Asks Claude to identify cross-source topics and synthesis opportunities
• Creates/updates wiki/concepts/ pages with multi-source evidence
• Files gaps back to wiki log

When /pith compile --topic <topic> is called:

1. Run python3 tools/compile.py --topic "<topic>"

When /pith compile --dry-run is called:

1. Run python3 tools/compile.py --dry-run

• Shows plan (topics, synthesis pages, gaps) without writing anything

Lint checks

When /pith lint is called:

1. Run python3 tools/lint.py

• Structural: orphan pages, missing sources, broken index links, stale contradictions
• Semantic (LLM): cross-page contradictions, missing entity pages, suggested connections, knowledge gaps, imputable facts

When /pith lint --fix is called:

1. Run python3 tools/lint.py --fix

• Same as above + auto-creates stub pages for missing entities

When /pith lint --quick is called:

1. Run python3 tools/lint.py --quick

• Structural checks only, no LLM call

Query workflow

When /pith wiki "<question>":

1. Read index.md — identify relevant page entries
2. Load those pages (Pith compresses each read automatically)
3. Synthesize answer with citations: "Based on [[page1]] and [[page2]]..."
4. Offer to file the answer: "Worth saving this as a synthesis page?"

Boundaries

Never modify files in raw/sources/ — those are immutable source documents. Always write compressed, cross-linked pages. No verbose prose. Every new entity or concept gets its own page — no inline-only mentions.