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.